@pikku/core 0.12.143 → 0.12.144

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

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

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

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

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

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

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

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

package/knowledge/questions/index.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/knowledge/questions/unauthorized-channel-replies-escape-the-declared-out-type.md

@@ -1,44 +0,0 @@
----
-type: question
-title: An unauthorized channel reply is sent outside the channel's declared Out type
-description: processMessageHandlers sends a bare string on auth failure, which no generated client type admits — nobody has decided what the typed shape should be
-tags: core, channel
----
-
-# An unauthorized channel reply is sent outside the channel's declared Out type
-
-When a message arrives on a channel route that requires a session and none is
-attached, `processMessageHandlers` in
-`packages/core/src/wirings/channel/channel-handler.ts` logs the failure and then
-sends the client a bare string:
-
-```ts
-channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`)
-```
-
-That compiles only because `processMessageHandlers` takes
-`PikkuChannelHandler`, whose generics default to `<unknown, unknown>`, so `send`
-accepts anything at this call site. The channel the application actually
-declared has a concrete `Out`, and the generated client is typed from it. A
-client can therefore receive a value its own types say is impossible, and no
-`@pikku/client-websocket` consumer has a branch for it.
-
-The alternatives were never worked through:
-
-- **Widen every channel's `Out`** to `Out | ChannelError`, so the error is part
-  of the contract. Honest, but it forces a discriminated union on every consumer
-  including channels that can never fail auth.
-- **Send on a reserved envelope** the way `channel-rpc` does, and let the client
-  library surface it out-of-band rather than as a message. Keeps `Out` clean,
-  but adds a second framing that every runtime adapter has to honour.
-- **Send nothing** and let the close code carry it. Simplest, and loses the
-  route name that makes the failure debuggable.
-
-Until one is chosen the string stays, because dropping it silently is worse: a
-client that is quietly ignored has no way to tell "unauthorized" from "the
-server is slow".
-
-**What would settle it:** deciding whether channel-level errors belong in `Out`
-at all, which is the same question `channel-rpc` already answered for RPC frames
-by giving them their own envelope. If the answer is "same as RPC", this becomes
-a decision note and the string becomes an envelope.

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

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

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

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

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

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