@pikku/core 0.12.143 → 0.12.145

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

@@ -1,42 +0,0 @@
----
-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/virtual-user-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md

@@ -1,29 +0,0 @@
----
-type: decision
-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
----
-
-# Virtual user sign-in is proven by Set-Cookie, not a non-empty jar
-
-`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 virtual user running every subsequent
-request unauthenticated, and the scenario would report the resulting refusals as
-genuine permission failures.
-
-**What this rules out:** replacing `signedIn` with a `jar.isEmpty()` check,
-dropping the `getSetCookie().length === 0` guard as redundant with `res.ok`, and
-treating `signOut()` as jar-clearing only — it must reset the flag too, or the
-next call proceeds believing it has a session.

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

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

package/knowledge/decisions/security/webhook-bodies-are-signed-before-they-are-enqueued.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: Webhook bodies are signed before they are enqueued
-description: QueueWebhookService computes the HMAC at enqueue time so the signing key never travels in the queue payload
-tags: services
----
-
-# Webhook bodies are signed before they are enqueued
-
-`QueueWebhookService.prepareDelivery`
-(`packages/core/src/services/queue-webhook-service.ts`) serialises the payload,
-resolves the signing secret, computes the signature and writes it into the job's
-`headers` — all before `queueService.add` is called. The worker,
-`pikkuWebhookWorkerFunc`, POSTs headers it was handed and never sees a secret.
-
-Signing in the worker instead would mean the key has to reach the worker, and the
-only channel between the two is the queue payload: an SQS body, a Redis value, a
-`jsonb` column, all of which are at rest, replicated, and visible to anyone who
-can read the queue. The signature is not sensitive; the key is.
-
-**What this rules out:** moving signing into the worker so it can re-sign on
-retry, and putting `secret` (or a resolved key of any kind) onto `WebhookJobData`.
-Note the related consequence: because the signature is fixed at enqueue time, a
-key rotated between enqueue and delivery does not change an in-flight job's
-signature — that is intended, not a bug to fix by carrying the key.

package/knowledge/decisions/security/wire-addon-expose-selects-the-rpc-surface.md

@@ -1,51 +0,0 @@
----
-type: decision
-title: wireAddon expose selects the RPC surface, and a list may widen it
-description: The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
-tags: addon, rpc, expose, authorization
----
-
-# wireAddon expose selects the RPC surface, and a list may widen it
-
-`rpc.exposed('<name>:<fn>')` — what the generated `POST /rpc/:rpcName` forwards
-to — used to consult only the addon's own `expose: true`. The app installing the
-addon had no say: it could not close an addon whose author marked functions
-exposed, and it could not open one the author had not. `mcp` already worked the
-other way (the wiring decides), and the two now match.
-
-`expose` on `wireAddon` is `boolean | string[]`, resolved per instance by
-`isAddonFunctionExposed`:
-
-- **unset or `true`** — the addon's declaration decides, as before. Keeping the
-  default unchanged means no existing app gains or loses a route on upgrade.
-- **`false`** — nothing in this instance is reachable through `rpc.exposed`.
-- **a list** — exactly those functions, whether or not the addon declared them.
-  The list can widen the addon's surface, the same power `mcp` has, because the
-  app is the one that knows what its deployment should offer. The generated
-  `#pikku/addon` types the list against the package's function names, and a name
-  that survives to the build unpublished fails it with PKU343.
-  The value has to be written inline (`true`, `false` or an array of string
-  literals): the build reads it statically, and a variable or spread fails it
-  with PKU344 rather than being read as unset, which would leave the deploy
-  units disagreeing with the runtime.
-
-The decision is per **instance**, not per package: two `wireAddon` calls for one
-package may expose different things, and the gate reads the config the
-namespace resolved to.
-
-The deploy analyzer's per-addon unit applies the same rule, since that unit is
-what the dispatcher can forward to. A function the wiring refuses gets no unit
-and no dispatch entry, so the `deploymentService` fallback in `rpc.exposed` —
-which forwards namespaced names with no local metadata — has nothing to reach.
-Where the dispatcher does hold the wiring, it also refuses locally before
-forwarding.
-
-`expose` is reachability, not authorization. A listed function still runs
-through `runPikkuFunc` with its own `auth`, permissions and the instance's
-`auth`/`scopes`/`tags` — see
-[addon auth and tags](./addon-auth-and-tags-only-tighten.md). Widening the list
-to a sessionless function makes it public unless one of those gates it.
-
-**What this rules out:** letting the addon's `expose: true` override a wiring's
-`false`; treating an unknown list entry as a silent no-op; and a deploy unit
-that carries functions the runtime gate would refuse.

package/knowledge/decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md

@@ -1,40 +0,0 @@
----
-type: decision
-title: An approval decision is stored raw and validated on replay, and an invalid one closes the gate rather than failing the run
-description: The schema only exists inside the workflow body, and letting an external payload fail the run would let any caller kill a workflow
-tags: workflow
----
-
-# An approval decision is stored raw and validated on replay, and an invalid one closes the gate rather than failing the run
-
-`approveStep` in `pikku-workflow-service.ts` is called from outside the workflow
-— an HTTP route, an RPC — where the approval's schema value is not in scope. It
-therefore stores the decision payload raw in run state and does nothing else.
-Validation happens on replay inside `approvalStep`, in the workflow body, which
-is the only place the schema exists.
-
-When validation fails, the bad decision is dropped, the issues are recorded on
-the gate's state record, and a `WorkflowSuspendedException` re-closes the gate.
-The failure stays legible to whoever tries next, and — the security point —
-failing the run instead would let any caller kill a workflow with a malformed
-payload. A later valid decision still lands normally.
-
-`WorkflowApprovalOptions.schema` is a VALUE, not a type generic, for the same
-reason: the payload arrives from an untrusted caller over the approve wire, and
-a generic is erased at compile time, so it would validate nothing. Any
-standard-schema library (zod, valibot, arktype) satisfies it. The contract is
-the `~standard` spec and nothing more: `@pikku/core` deliberately carries no
-zod dependency, which is why `pikku-workflow-service.test.ts` hand-rolls a
-minimal `StandardSchemaV1` rather than importing a validation library.
-
-A decision arriving for a gate that has already resolved is rejected with
-`WorkflowApprovalResolvedError` (409) rather than accepted and dropped. The gate
-caches its outcome as the step result and never re-reads run state, so a
-decision recorded after resolution could not take effect — most obviously when
-it loses the race with expiry — and the approver has to be told their decision
-did not land.
-
-**What this rules out:** validating in `approveStep` (the schema is not there),
-failing the run on an invalid payload, turning `schema` into a type parameter,
-accepting a decision on a resolved gate, or making a resolved gate re-read run
-state so a late decision "wins".

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

@@ -1,18 +0,0 @@
----
-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-queued-steps-rehydrate-their-session-from-the-run-wire.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: A queued workflow step rehydrates its session from the persisted run wire
-description: The queue job payload is just `{ runId }`, so without threading `pikkuUserId` an authed step sees no session and throws
-tags: workflow
----
-
-# A queued workflow step rehydrates its session from the persisted run wire
-
-A queued workflow step is executed with the bare job wire — the payload is just
-`{ runId }` (or `{ runId, stepName, rpcName, data, fromStepName }`) — so it
-carries no `pikkuUserId`. `invokeStepRpc` in `pikku-workflow-service.ts`
-therefore merges the run's own `wire.pikkuUserId` into the step wire override
-before calling `rpcWithWire`. Without it, a step written as an authed
-`pikkuFunc` sees no session and fails with "Authentication required" on the
-queued path while passing inline, which is the worst possible split: it looks
-like a transport bug rather than an auth one.
-
-`invokeStepRpc` is shared by the queue executor and the inline executor
-precisely so the two cannot drift. The only thing that differs between
-transports is who calls it, not the call itself. `createWorkflowWire` and
-`runWorkflowJobInner` propagate the same `pikkuUserId` onto the workflow wire
-for the workflow body.
-
-The user id is the only identity carried. It is a reference for credential
-resolution, not a serialized session — the session itself is rehydrated on the
-far side.
-
-**What this rules out:** giving the queued path its own invocation helper,
-dropping the `pikkuUserId` merge because "the wire already has a session"
-inline, or widening the run wire to persist session tokens instead of a user id
-reference.

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

@@ -1,32 +0,0 @@
----
-type: decision
-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 virtual user and reset between scenarios
-
-`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
-rotates mid-session is followed rather than dropped, and an empty `Set-Cookie`
-value is treated as a deletion — the name is dropped rather than held as a
-cookie whose value says it is gone. The jar also stamps `Origin`, because Better
-Auth rejects a state-changing POST whose Origin does not match its baseURL.
-
-`ScenarioCookieJar.empty` reports a fact about the jar, not about the session: a
-target that sets a CSRF or locale cookie before anyone signs in fills the jar
-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 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 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,31 +0,0 @@
----
-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 a virtual user's session, so exposing it as an RPC would put that reach on the network
-tags: workflow
----
-
-# A scenario step is never registered as a callable RPC and never dispatched on the queue
-
-`ScenarioStepMeta` in `dsl/workflow-dsl.types.ts` is a distinct meta type from
-`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 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 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 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 a virtual user.

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

@@ -1,34 +0,0 @@
----
-type: decision
-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 virtual user step always goes over the real transport and never through internal dispatch
-
-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 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, 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.
-
-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
-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

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

@@ -1,24 +0,0 @@
----
-type: overview
-title: Knowledge
-description: Why @pikku/core is built the way it is — the reasoning that used to live in comments
----
-
-# Knowledge
-
-Pikku's source says _what_ it does. These notes say _why_, for the handful of
-choices where the code alone reads as arbitrary or, worse, reads as a mistake.
-
-The rule that produced this directory: **reasoning never lives in code.** A
-comment that restates the line below it is deleted. A comment that records a
-decision — a constraint, a trade-off, a thing that was tried and failed — moves
-here and gets a name, so it can be linked to and argued with.
-
-Everything mechanical is generated or inspectable: the wirings, the schemas, the
-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

@@ -1,24 +0,0 @@
----
-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/channel-middleware-accepts-bare-factories-that-nothing-resolves.md

@@ -1,35 +0,0 @@
----
-type: question
-title: A channel's middleware list accepts bare factories that nothing ever resolves
-description: CoreChannel.channelMiddleware admits CorePikkuChannelMiddlewareFactory, but no runner calls one, so a bare factory would stall the chain
-tags: core, channel
----
-
-# A channel's middleware list accepts bare factories that nothing resolves
-
-`CoreChannel.channelMiddleware` is typed as
-`(CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory)[]`, but
-`runPikkuFunc`'s `wireChannelMiddleware` parameter admits only
-`CorePikkuChannelMiddleware[]`. The two call sites that bridge them —
-`channel-common.ts` and `channel-handler.ts` — assert across the gap.
-
-A factory is `(input: In) => CorePikkuChannelMiddleware`: the author is meant to
-_call_ it at wiring time and put the result in the array.
-`combineChannelMiddleware` contains no factory-resolution branch, and neither
-does `combineMiddleware` for ordinary middleware — that is consistent and
-deliberate. So a bare, uncalled factory in `channelMiddleware` would be pushed
-into the chain and then invoked as if it were middleware: it would receive
-`(services, channel, next)` as its single `input` argument, return a middleware
-function that nothing runs, and never call `next` — stalling the chain silently.
-
-Nothing in this repository puts a bare factory there, so the failure is
-hypothetical today. The type is what invites it.
-
-**What would settle it:** deciding whether `channelMiddleware` should accept
-only resolved middleware — in which case the union is simply wrong and should
-lose its factory arm, and both assertions disappear — or whether the runner
-should resolve factories, in which case `combineChannelMiddleware` needs a
-branch and the ordinary middleware path probably needs the matching one.
-
-Until then the assertions name the exact target type rather than `as any`, so
-the gap is visible at both call sites.

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

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

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

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

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

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