@pikku/core 0.12.143 → 0.12.145

package/knowledge/decisions/security/a-virtual-user-catalogue-entry-is-filtered-by-scope-and-approval-is-denied-by-default.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: Virtual users are offered calls by declared scope, and approval-gated calls are denied by default
-description: The catalogue type filters by the declared scopes of each RPC rather than by permission functions, and the catalogue filter drops approval-required entries unless the caller opts in
-tags: core, virtual-users, scopes, approval
----
-
-# Virtual users are offered calls by declared scope, and approval-gated calls are denied by default
-
-`packages/core/src/wirings/virtual-user/virtual-user.types.ts` defines the
-catalogue entry a virtual user is offered.
-
-The `scopes` field lists the scopes the session must hold to call the RPC, all of
-them (`virtual-user.types.ts:92-99`). The doc comment explains why scopes and not
-permission functions: a scope is "declared and checkable", while "a permission is
-arbitrary code whose verdict nobody can predict without running it"
-(`virtual-user.types.ts:95-97`).
-
-`approvalRequired` is documented as "denied by default" (`virtual-user.types.ts:89-90`).
-The filter in `virtual-user-catalogue.ts` enforces this. It drops an entry when
-`approvalRequired` is set and the caller has not passed `allowApprovalRequired`
-(`virtual-user-catalogue.ts:113`), and that flag defaults to `false`
-(`virtual-user-catalogue.ts:95`).
-
-The same filter drops any entry the session's scopes do not cover
-(`virtual-user-catalogue.ts:115-117`).
-
-**What this rules out:** a virtual user calling an approval-gated RPC unless the
-run explicitly allows it, and a permission function being used to decide what a
-virtual user can see.

package/knowledge/decisions/security/a-virtual-user-environment-fails-closed.md

@@ -1,38 +0,0 @@
----
-type: decision
-title: A virtual user's sign-in is refused unless the environment is known and allowed
-description: Virtual user provisioning, sync and sign-in refuse when PIKKU_ENV is unresolved, unknown, production without the accountable disposition, or outside the virtual user's environments, and production environments are omitted by default
-tags: core, virtual-users, environments, security
----
-
-# A virtual user's sign-in is refused unless the environment is known and allowed
-
-`virtualUserEnvironmentRefusal`
-(`packages/core/src/wirings/virtual-user/virtual-user-environments.ts`) fails
-closed when:
-
-- `PIKKU_ENV` is unresolved;
-- `PIKKU_ENV` names an environment the config does not know;
-- the environment is production and the virtual user's disposition is not
-  `PRODUCTION_DISPOSITION` (`accountable`);
-- the environment is not one the virtual user may target.
-
-`resolveVirtualUserEnvironments` leaves production environments out when a
-virtual user declares no `environments`. A virtual user reaches production only
-when someone has named it there. The build-time half is
-`virtualUserEnvironmentErrors`, which the doc comment says the inspector runs;
-the run-time half is re-checked because "the run check does not trust which
-artifact got deployed".
-
-The refusal is applied by `pikku virtual-user sync`
-(`packages/cli/src/functions/commands/virtual-user-sync.ts`), by the
-`pikku virtual-user` command (`packages/cli/src/functions/commands/virtual-user.ts`)
-and by `provisionVirtualUsers`
-(`packages/services/better-auth/src/provision-virtual-users.ts`).
-
-**What this rules out:** provisioning or signing in virtual users when the target
-environment is ambiguous, and a production stage that carries virtual users it was
-never meant to have.
-
-Runs are stricter: [A virtual user never runs against production](a-virtual-user-never-runs-against-production.md)
-refuses even the `accountable` disposition.

package/knowledge/decisions/security/a-virtual-user-is-never-offered-a-step-that-would-forge-its-own-oracle.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: A virtual user is never offered a scenario, platform or addon step
-description: Being able to invoke "the webhook arrives" lets the user manufacture the outcome it exists to discover, which invalidates every finding downstream
-tags: core, virtual-user
----
-
-# A virtual user is never offered a scenario, platform or addon step
-
-`deriveVirtualUserCatalogue` excludes scenario bodies and their steps, and
-platform and addon steps, from what a virtual user may call.
-
-For scenario bodies the argument is only efficiency: they are held out of every
-deployed unit and are not network-callable, so offering one wastes a turn on a 404.
-
-For a platform or addon step the argument is the oracle itself. A virtual user's
-findings are worth something _because_ it cannot manufacture the outcomes it is
-meant to discover. A user that could invoke "Stripe's webhook arrives" forges its
-own payment success, and every finding downstream of that forgery is worthless —
-not merely unreliable, but actively misleading, because it looks like evidence.
-
-This is the same class of argument as `allowApprovalRequired` defaulting to
-false, and it is enforced here at derivation rather than left to convention.
-
-**What this rules out:** exposing platform steps behind a flag "for
-convenience", or filtering them later in the run loop where a caller could skip
-the filter.

package/knowledge/decisions/security/a-virtual-user-never-runs-against-production.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: A virtual user never runs against production, whatever its disposition
-description: startVirtualUserRun and an enabling writeVirtualUserSchedule both refuse with a 403 in production, including for the accountable disposition; an unresolved environment counts as production
-tags: core, virtual-users, environments, security
----
-
-# A virtual user never runs against production, whatever its disposition
-
-`refuseInProduction` (`packages/core/src/wirings/virtual-user/virtual-user-scaffold.ts:192`) throws a `ForbiddenError`, "Virtual users do not run against production", whenever the process is a production run. It has no disposition exception: `accountable`, which the virtual user environment check still accepts at sign-in in production, is refused here too.
-
-It is called from two places:
-
-- `startVirtualUserRun` (`virtual-user-scaffold.ts:232`), before the run record is created, so a refused run leaves no row.
-- `writeVirtualUserSchedule` (`virtual-user-scaffold.ts:410`), only when the row is or becomes enabled. Disabling a schedule, or editing one that is off, is still allowed in production so a leftover schedule can be stopped. A scheduled tick dispatches `runVirtualUser` through `rpc.invoke` (`packages/cli/src/functions/wirings/virtual-user/serialize-virtual-user-functions.ts:563-566`), and that function calls `startVirtualUserRun` (same file, line 337), so a due tick is refused as well.
-
-"Production" is decided by `isProductionRun` (`virtual-user-scaffold.ts:179`). The configured `PIKKU_ENV` environment wins when the project configures environments, and an unresolved environment counts as production. `NODE_ENV` decides only for a project that configures none.
-
-The sign-in environment rule is separate and unchanged. See [A virtual user's sign-in is refused unless the environment is known and allowed](a-virtual-user-environment-fails-closed.md): signing an `accountable` virtual user in against production is still allowed there, and starting a run is not.
-
-The tests are in `virtual-user-scaffold.test.ts`: "refuses every disposition in production", "the accountable disposition is refused in production too", "an accountable cadence is refused in production too" and "disabling or editing an off cadence is allowed in production".
-
-**What this rules out:** a virtual user, probing or not, acting on real customers' data, and an enabled schedule that can only ever fail to start in production.

package/knowledge/decisions/security/a-virtual-user-reads-its-roles-from-the-apps-own-rpc-before-better-auth.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: A virtual user reads its roles from the app's own RPC before better-auth's user.role
-description: sessionRoles asks getMyScopes first, then get-session, and returns null rather than an empty list when the stage reports no roles
-tags: core, virtual-users, auth
----
-
-# A virtual user reads its roles from the app's own RPC before better-auth's user.role
-
-`HttpVirtualUser.sessionRoles` (`packages/core/src/services/http-virtual-users.ts`) answers
-"what roles does this session hold" in a fixed order. First the app's exposed RPC,
-which defaults to `getMyScopes` and can be renamed or switched off with `rolesRpc`.
-Only then better-auth's `get-session`, where its admin plugin puts `role` on the
-user.
-
-The `rolesRpc` doc comment gives the reason. In an app that authorizes on scopes,
-`user.role` is "a projection rather than the model": it exists so better-auth's
-admin endpoints have something to read, and it may be absent. A virtual user verified
-against it is verified against a copy.
-
-Two answers are kept apart. A stage that answers neither returns `null`, which
-means "this stage does not report roles". A session that carries a user with no
-role field returns `[]`, which means "this person has none". The doc comment says
-the two call for opposite responses from the caller.
-
-**What this rules out:** making better-auth's `user.role` the first source of a
-virtual user's roles, and reporting `[]` for a stage that could not answer at all.

package/knowledge/decisions/security/a-virtual-user-run-treats-an-unresolved-environment-as-production.md

@@ -1,41 +0,0 @@
----
-type: decision
-title: A virtual-user run treats an unresolved PIKKU_ENV as production
-description: The virtual-user scaffold decides "production" from the configured PIKKU_ENV environment, counts an unresolved one as production, and falls back to NODE_ENV only when no environments are configured
-tags: core, virtual-users, environments, security
----
-
-# A virtual-user run treats an unresolved PIKKU_ENV as production
-
-`startVirtualUserRun` calls `refuseInProduction` before it creates a run record
-(`packages/core/src/wirings/virtual-user/virtual-user-scaffold.ts:232`). `PIKKU_ENV`
-is read as the default for `environment` (`virtual-user-scaffold.ts:217`). The
-schedule writer runs the same check when the schedule is or becomes enabled
-(`virtual-user-scaffold.ts:399`, `:409-411`).
-
-`refuseInProduction` throws a `ForbiddenError` whenever `isProductionRun` is true,
-whatever the disposition (`virtual-user-scaffold.ts:192-204`). That rule is
-[a virtual user never runs against production](a-virtual-user-never-runs-against-production.md);
-this note is about how "production" is decided.
-
-`isProductionRun` decides it as follows (`virtual-user-scaffold.ts:179-188`):
-
-- With no environments configured, it is `NODE_ENV === 'production'` (`:184-186`).
-- With environments configured and `PIKKU_ENV` unset, it is true (`:187`,
-  `environment ? ... : true`).
-- With `PIKKU_ENV` set, it is that environment's `production` flag (`:187`). An
-  unknown name evaluates to false in this check. `virtualUserEnvironmentRefusal`
-  refuses unknown names at sign-in instead
-  (`packages/core/src/wirings/virtual-user/virtual-user-environments.ts:113-119`).
-
-The comment gives the reasons. The configured environment wins over `NODE_ENV`
-because a production mirror runs `NODE_ENV=production` too
-(`virtual-user-scaffold.ts:166-172`). An unresolved environment counts as
-production because nobody can vouch for its data (`:174-177`).
-
-See also [a virtual user's sign-in is refused unless the environment is known and allowed](a-virtual-user-environment-fails-closed.md),
-which covers the sign-in refusal in `virtual-user-environments.ts`.
-
-**What this rules out:** starting a run when the environment cannot be named, and
-keying the scaffold's refusal on `NODE_ENV` in a project that has configured
-environments.

package/knowledge/decisions/security/a-virtual-user-scopes-are-expanded-from-its-roles-once-at-run-preparation.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A virtual user's scopes are expanded from its roles once, at run preparation
-description: A virtual user's scope set is computed from its declared roles against the defineSystemRole definitions when the run is prepared, and that set is the oracle for scope drift
-tags: core, virtual-user, auth
----
-
-# A virtual user's scopes are expanded from its roles once, at run preparation
-
-`virtualUserScopes` in `packages/core/src/wirings/virtual-user/prepare-virtual-user-run.ts`
-expands a virtual user's `roles` into scopes through the role definitions the seed
-grants from. Its doc comment says roles are the only thing a virtual user declares, and
-that the expansion happens "once, here, against the same `defineSystemRole`
-definitions the seed grants from".
-
-The result feeds two things in `run-virtual-user.ts`. It narrows the catalogue
-for a non-adversarial user, and it is the oracle: a call that succeeds on an
-endpoint whose `scopes` the virtual user does not hold is recorded as
-`unexpected-success`, which the code calls authorization drift. Using the static
-expansion as the truth is what makes that finding mean something, because the
-run never asks the target what the virtual user may do.
-
-**What this rules out:** building a virtual user's catalogue or judging its
-successes from a scope list fetched from the live session, which would make the
-oracle agree with whatever the target currently grants.

package/knowledge/decisions/security/a-virtual-user-whose-roles-drift-from-the-declaration-refuses-to-run.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: A virtual user whose granted roles drift from its declaration refuses to run
-description: verifyVirtualUserRoles compares declared and granted roles in both directions before a run, and roleMismatchMessage produces the refusal text; a provider login is never runnable
-tags: core, virtual-users, roles, drift
----
-
-# A virtual user whose granted roles drift from its declaration refuses to run
-
-`packages/core/src/wirings/virtual-user/validate-virtual-users.ts` has the role check that
-runs before a virtual user's first step. `verifyVirtualUserRoles` computes what is missing
-and what is extra, in both directions (`validate-virtual-users.ts:94-111`). `roleMismatchMessage`
-returns `null` when they match, and otherwise a message that ends with "Refusing
-to run" (`validate-virtual-users.ts:114-133`, the text at `validate-virtual-users.ts:131`).
-
-The doc comment says the declaration is authoritative, but a run may target a
-stage that the generated seed never touched (`validate-virtual-users.ts:84-87`). It
-gives a reason for each direction: an under-granted virtual user reports seed drift
-as an authorization bug, and an over-granted one "silently stops testing the
-boundary it was written to test" (`validate-virtual-users.ts:89-92`).
-
-Nothing in `packages/core/src` calls `roleMismatchMessage`. The caller that
-stops the run is the `pikku virtual-user` command
-(`packages/cli/src/functions/commands/virtual-user.ts`), so this file only
-supplies the check and the message.
-
-`isRunnableVirtualUser` (`validate-virtual-users.ts:19-27`) returns false for a virtual user
-with `runnable: false`, and for any virtual user with an account provider, because
-driving a provider consent screen "needs a human" (`validate-virtual-users.ts:10-12`).
-
-**What this rules out:** running a virtual user whose roles no longer match what
-it declared, and a provider-login virtual user being driven by a run.

package/knowledge/decisions/security/a-workflow-run-is-read-and-approved-by-its-owner.md

@@ -1,50 +0,0 @@
----
-type: decision
-title: A workflow run is read by its owner, and answered by whoever its gate declares
-description: A run started through a session records that user and only that user may read it; who may answer an approval gate is the gate's own declaration, and a run with no recorded owner has no ownership to enforce
-tags: workflow
----
-
-# A workflow run is read by its owner, and answered by whoever its gate declares
-
-`WorkflowRunWire.pikkuUserId` has always been recorded on every run started
-through a session — `RPCService.startWorkflow` copies it off the wire — and
-nothing read it back. Run ids were the only secret protecting both the status
-routes (which stream `output` and `error`) and `approveStep`, which took no
-session at all and rejected only an already-resolved gate.
-
-`assertWorkflowRunOwner`
-(`packages/core/src/wirings/workflow/workflow-run-ownership.ts`) is the check the
-**read** paths share: the generated status routes assert it against the run they
-were already reading.
-
-**A run with no recorded owner is not gated.** Triggers, schedulers and routes
-wired without auth start runs with no `pikkuUserId`; there is nobody to compare a
-caller against, and inventing one would reject the framework's own callers rather
-than secure anything. Gate those at the entrypoint with `auth` or `permissions`.
-
-This is ownership, not an approver model. It answers "is this your run", not "are
-you entitled to approve this particular gate".
-
-## Approving is a separate question, and the gate answers it
-
-`approveStep` originally shared `assertWorkflowRunOwner`, which made "only the
-initiator may answer" the one available rule. That is right for "confirm your own
-action" and exactly wrong for four-eyes sign-off, where the initiator is the one
-person who must not sign. Which applies is a property of the decision, so it is
-declared on the gate — `approvers` (`'any' | 'owner' | 'not-initiator'`) and
-`approverScope` on `WorkflowApprovalOptions`.
-
-It is enforced wherever the policy is known. Reaching the gate publishes the
-policy into the run state, so a decision submitted after that is judged by the
-approve entrypoint and refused with a 403. A decision can legitimately be
-recorded before the run has reached the gate, and that one has no policy to be
-judged against yet — it is judged on replay instead, alongside payload
-validation, and discarded if it fails.
-
-The default is therefore `any`: a gate is a pause for a decision, not an
-authorization boundary, and a route that needs one has `auth`/`permissions`.
-
-**What this rules out:** treating a run id as a capability, adding a new run read
-path that does not take a session, and re-deriving who may approve from who
-started the run.

package/knowledge/decisions/security/addon-auth-and-tags-only-tighten.md

@@ -1,43 +0,0 @@
----
-type: decision
-title: Addon auth and tags only tighten, and resolve where the function runs
-description: wireAddon auth and tags are applied in runPikkuFunc like scopes, but auth:false is ignored and tags resolve against the consuming app's tag groups rather than the addon package's
-tags: addon, auth, tags, authorization
----
-
-# Addon auth and tags only tighten, and resolve where the function runs
-
-`wireAddon({ auth, tags })` was read only by `resolveAddonFunction` in
-`rpc-runner.ts`, which covers the `namespace:function` RPC form alone. Every
-direct wiring — the inspector writes the addon's package name onto http,
-channel, schedule, queue, cli, trigger, gateway and mcp wirings — reached
-`runPikkuFunc` with a `packageName` and neither value. That is the same hole
-[addon scopes](./addon-scopes-are-resolved-where-the-function-runs.md) had, and
-it is closed the same way: `runPikkuFunc` resolves both from the addon config.
-
-`auth` merges as an OR and `auth: false` is ignored. The RPC path treats it as a
-default (`addonConfig?.auth ?? options.requiresAuth`) because there the addon
-config is the only statement of intent. On a direct wiring the route already
-carries its own `auth`, so honouring `false` would let an addon _weaken_ a gate
-the app wrote — the inverse of what a wiring-level declaration should be able to
-do. An addon may require a session the wiring did not; it may never waive one
-the wiring did.
-
-Tags resolve against the **root** tag groups, not the addon package's. A tag on
-`wireAddon` is written by the consuming app, and `addTagMiddleware('admin', …)`
-in that app registers under the root package. `combineMiddleware` looks tag
-metadata up under the `packageName` it is given, which for an addon function is
-the addon's own namespace — where the app's middleware does not exist. Resolving
-addon tags to concrete middleware before the call and passing them as
-`wireMiddleware` is what keeps `wireAddon({ tags: ['admin'] })` from being
-silently inert, which is the failure mode the whole gate exists to avoid.
-
-A function's own tags are unaffected: the inspector already emits them as
-`{ type: 'tag' }` entries on the function and wiring meta, resolved under the
-package that declared them. The `tags` argument `runPikkuFunc` accepts is
-separate and still unused on every path.
-
-**What this rules out:** honouring `auth: false` from an addon on a direct
-wiring; resolving addon tags under the addon's `packageName`; and folding addon
-tags into `funcInheritedMiddleware`, which would resolve them in the wrong
-namespace and double-apply the function's own tags.

package/knowledge/decisions/security/addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md

@@ -1,52 +0,0 @@
----
-type: decision
-title: Addon auth and tag gates apply wherever the function runs, including inside the addon
-description: wireAddon's auth and tags moved from the namespaced RPC boundary into runPikkuFunc, so they also apply to direct wirings and to bare intra-addon calls
-tags: rpc, addon, auth
----
-
-# Addon auth and tag gates apply wherever the function runs, including inside the addon
-
-`ContextAwareRPCService.invokeAddonFunction` used to be the only place that
-applied an addon's `addonConfig.auth` and `addonConfig.tags`, making them a
-perimeter control on `rpc('namespace:fn')`. That perimeter had a hole in it: the
-inspector writes the addon's package name onto http, channel, schedule, queue,
-cli, trigger, gateway and mcp wirings, and every one of those runners calls
-`runPikkuFunc` directly without resolving a namespace. A consumer who wrote
-`wireAddon({ auth: true })` and then wired an addon function to a route got no
-gate at all.
-
-Both values now resolve in `runPikkuFunc`, the one point every path shares —
-the same move, for the same reason, as
-[addon scopes](./addon-scopes-are-resolved-where-the-function-runs.md). See
-[addon auth and tags only tighten](./addon-auth-and-tags-only-tighten.md) for
-the merge rules.
-
-This replaces a consequence an earlier decision accepted: a bare `rpc('fn')`
-made from inside an addon now re-applies the gate, because it reaches
-`runPikkuFunc` with the addon's `packageName` like any other call. The earlier
-reasoning — that the perimeter had already been passed, so re-checking would
-gate internal calls on a consumer-facing setting — held only while the perimeter
-was real. Once a direct wiring could enter the addon without passing any gate,
-"already inside" stopped being something the runtime could infer, and the choice
-became re-checking or trusting an entry that may never have happened.
-
-In practice an intra-addon call inherits the entry point's session, so the auth
-check passes wherever the entry was itself authenticated. What it does break is
-an addon that wires `auth: true` and also runs its own sessionless internal
-work — a scheduled task or queue worker inside the addon calling a sibling. Such
-an addon should carry authorization on the function via
-`pikkuFunc({ permissions })`, which has always been enforced on every path,
-rather than on the consumer-facing `wireAddon` setting.
-
-Re-checking was chosen over provenance because the marker that would make
-"already inside" knowable — set by the runtime, unsettable by any caller outside
-the process, threaded through all eight runners — is a design problem of its
-own, and shipping it inside a security fix would have meant landing an untested
-trust signal alongside the gate that depends on it. Adding that marker is
-tracked separately; until it exists, re-checking is the only option that does
-not trust an entry which may never have happened.
-
-**What this rules out:** treating `addonConfig.auth` as a perimeter-only
-control; and inferring "already inside the addon" from the wire, which a direct
-wiring does not set.

package/knowledge/decisions/security/addon-scopes-are-resolved-where-the-function-runs.md

@@ -1,46 +0,0 @@
----
-type: decision
-title: Addon scopes are resolved where the function runs
-description: wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace
-tags: addon, scopes, authorization
----
-
-# Addon scopes are resolved where the function runs
-
-`wireAddon({ scopes })` names scopes every function in the addon's package
-requires. `runPikkuFunc` calls `resolveAddonScopes(packageName,
-addonInstance?.namespace)` and unions the result with the function's own
-`scopes` before `verifyScopes`.
-
-The obvious home for this is `resolveAddonFunction` in `rpc-runner.ts`, next to
-where `auth` and `tags` are already merged from the addon config — but that
-covers only the `namespace:function` RPC form. An addon function is reachable
-without any namespace resolution: the inspector's `resolveAddonName` writes the
-addon's package name onto the wiring meta whenever a wiring's `func` is an
-identifier imported from a wired addon, and every runner (`http-runner`,
-`mcp-runner`, channel, scheduler, queue, cli, trigger, gateway) then passes that
-`packageName` straight to `runPikkuFunc`. `refHTTP` / `refChannel` / `refCLI`
-contracts do the same through `registerHTTPRouteMeta`. A gate at namespace
-resolution would leave every one of those doors open while reading as complete,
-which is worse than no gate. `runPikkuFunc` is the one point all of them share.
-
-Merging is a union, not an override, because `firstUnsatisfied` in `scopes.ts`
-requires every listed scope. An addon scope is therefore an additional
-requirement and can only narrow access — an addon can never weaken a function
-that declares stricter scopes of its own. `ref('namespace:fn')` routes are
-gated for the same reason from the other direction: the generated wrapper is a
-local function that calls `rpc.invoke`, so the addon's scopes attach on the
-inner call rather than the route.
-
-When the caller carries an `addonInstance`, its namespace selects that
-instance's scopes exactly. The direct-wiring paths know only a package name, so
-`resolveAddonScopes` unions the scopes of every namespace the package is wired
-under. One package wired twice with different scopes is rare; taking the
-stricter reading keeps the unnamed path from becoming the weak one.
-
-**What this rules out:** gating addon functions in `resolveAddonFunction`,
-`resolveNamespace`, or any per-wiring runner; treating addon scopes as a
-default that a function's own `scopes` replaces; resolving a package's scopes
-by first matching namespace, the way `findAddonNamespaceForPackage` resolves
-services; and reusing this for `wireRemoteAddon`, whose functions execute on the
-host and are gated there.

package/knowledge/decisions/security/addon-screen-scopes-hide-and-do-not-enforce.md

@@ -1,20 +0,0 @@
----
-type: decision
-title: Addon screen scopes hide a screen and do not enforce access
-description: The scopes on a defineScreens entry state what a viewer must hold to see the screen; the addon's own functions are the access check
-tags: core, addons, screens, security
----
-
-# Addon screen scopes hide a screen and do not enforce access
-
-`packages/core/src/wirings/addon/define-screens.ts:7-8` documents `scopes` on an
-addon screen as required of the viewer to see it, and says the addon's functions
-must enforce the same scopes, because hiding a screen is not access control.
-
-The field is read statically by `pikku all`, which is why `scopes` must be a
-literal (`define-screens.ts:32`). Within `packages/core/src`, no code reads a
-screen's `scopes` at runtime; `wire-addon.ts:47-48` mounts the screens under
-`/addons/<name>` and is the only other place they are referenced.
-
-**What this rules out:** relying on a screen's scopes to keep data from a viewer,
-and an addon shipping a function that trusts the screen to have been hidden.

package/knowledge/decisions/security/agent-approval-forwarding-requires-a-symbol-brand.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: Only a Symbol-branded framework result can request tool approval
-description: Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
-tags: agent
----
-
-# Only a Symbol-branded framework result can request tool approval
-
-`checkForApprovals` in
-`packages/core/src/wirings/agent/agent-stream.ts` honours a forwarded
-approval only when both hold: the tool declares `forwardsApproval` (set solely by
-framework code on the sub-agent delegating tools built in
-`agent-prepare.ts`), and its result carries the `APPROVAL_REQUIRED` unique
-Symbol. The companion `__approvalRequired` string key exists for transport, but
-is never what the decision reads.
-
-A tool result is attacker-influenceable — a retrieved document, a third-party API
-response, or a sub-agent's LLM-shaped `result.object`. All of those are plain
-JSON, and plain JSON cannot carry a Symbol. Trusting the string key would let any
-ordinary tool conjure a suspension and an approval prompt showing a tool name and
-arguments of its choosing.
-
-**What this rules out:** checking `'__approvalRequired' in result` as the
-condition; replacing the Symbol with a string or numeric sentinel so results
-survive JSON serialization; and setting `forwardsApproval` from user-supplied
-tool configuration rather than from framework code.

package/knowledge/decisions/security/agent-credential-requests-are-symbol-branded.md

@@ -1,37 +0,0 @@
----
-type: decision
-title: Credential requests are trusted only when Symbol-branded
-description: The string key is a wire field; the Symbol is the capability, and only core can mint it
-tags: agent
----
-
-# Credential requests are trusted only when Symbol-branded
-
-A tool result asking the run to suspend and prompt for a credential is honoured
-only when it carries the `CREDENTIAL_REQUIRED` Symbol minted in
-`agent-prepare.ts`. `checkForCredentialRequests` in `agent-stream.ts`
-tests for that Symbol, never for the `__credentialRequired` string key that
-travels beside it on the wire.
-
-The distinction is the whole security property. Tool results are frequently
-attacker-influenceable — a retrieved document, an echo from a third-party API,
-LLM-authored content round-tripping through a tool — and any of those can carry
-a string key. None can carry a Symbol, because a Symbol has no literal form and
-does not survive JSON. Without the brand, an influenced tool result could
-suspend the run and push a `credential-request` event with an attacker-chosen
-`connectUrl`, which the client renders as a "Connect" button: a phishing
-primitive inside the product's own UI. This mirrors the `APPROVAL_REQUIRED`
-brand, which exists for the identical reason one function over.
-
-The brand survives because the object is passed by reference the whole way —
-core's `buildToolDefs` wrapper returns it, the Vercel adapter's `agentTool` hands
-it back verbatim, and the AI SDK puts the raw value on the stream part rather
-than the JSON form it builds separately for the model.
-
-**What this rules out:** widening the check to `'__credentialRequired' in
-result` for convenience, or introducing any path where a credential request is
-reconstructed from parsed JSON rather than passed by reference — either one
-silently converts the gate into a formality. Note the inverse holds for the
-`credentialFilteredChannel` suppression later in the same file: that one
-deliberately matches the _string_ key, because it hides tool results from the
-client and a broader match leaks less, not more.

package/knowledge/decisions/security/agent-gate-requires-a-session-only-when-auth-is-true.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: An agent requires a session only when auth is true, but always enforces scopes and permissions
-description: Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O
-tags: agent
----
-
-# An agent requires a session only when auth is true, but always enforces scopes and permissions
-
-`assertAgentAuthorized` in
-`packages/core/src/wirings/agent/agent-prepare.ts` enforces, in order:
-session presence (only when `CoreAgent.auth === true`), then `scopes`, then
-`permissions`. The ordering mirrors the function runner — scopes AND together so
-they can only narrow access, and a missing scope short-circuits before any
-permission function does I/O. Declared `scopes` are narrowed to the generated
-`ScopeId` union in a project's `#pikku/scopes`, so an undeclared scope is a
-compile error.
-
-`auth` defaults to `false` (i.e. `pikkuSessionlessFunc`, not `pikkuFunc`) because
-an agent is normally reached from a function that already enforced its own auth,
-and is also run from genuinely sessionless contexts such as crons and queue
-workers. Requiring a session by default would reject those without adding a real
-gate. Global permissions are evaluated here too rather than assumed to have
-already run, because an agent is reachable from entry points that never pass
-through the function runner; re-evaluating an AND gate of side-effect-free
-predicates is idempotent.
-
-**What this rules out:** making `auth: true` the default; checking permissions
-before scopes; skipping globals on the assumption a caller already ran them; and
-moving the gate into the individual run/stream/resume entry points, where a new
-entry point would silently miss it.

package/knowledge/decisions/security/agent-ownership-failures-never-echo-the-resource.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: An agent ownership failure never echoes the resource it refused
-description: assertResourceOwner throws a bare ForbiddenError so the error cannot be used as an existence oracle, at the cost of thinner debugging output
-tags: agent
----
-
-# An agent ownership failure never echoes the resource it refused
-
-`assertResourceOwner` in
-`packages/core/src/wirings/agent/agent-prepare.ts` compares a stored
-thread/run `resourceId` against the caller's composed owner key and throws
-`ForbiddenError('Not authorized to access this thread' | '… run')` on a
-mismatch. The message deliberately carries no id.
-
-Including the id would turn the endpoint into an existence oracle: a caller
-enumerating thread ids could tell "exists but is not yours" apart from "does not
-exist", which leaks the shape of other tenants' data even though no content is
-returned.
-
-**What this rules out:** improving the error message by interpolating the
-`threadId`, `runId`, or owner key into it, and distinguishing not-found from
-not-authorized on the read paths.

package/knowledge/decisions/security/agent-resume-re-runs-the-authorization-gate.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: Resuming a suspended agent run re-runs the agent's authorization gate
-description: Ownership of the run is not enough — a grant revoked while the run was suspended must block the approval
-tags: agent
----
-
-# Resuming a suspended agent run re-runs the agent's authorization gate
-
-Both `resumeAgent` (`agent-stream.ts`) and `resumeAgentSync`
-(`agent-runner.ts`) call `assertAgentAuthorized` after asserting run
-ownership and before touching `agentRunState.resolveApproval`.
-
-Ownership proves the run belongs to the caller, not that the caller may still
-act on it: a suspension can outlive the permission that created it, and the whole
-point of an approval gate is that the person approving is authorized at the
-moment of approval. Resolving an approval is a persisted side effect, so the
-gate must run before it, not after.
-
-**What this rules out:** treating the ownership assertion as the complete
-authorization check on the resume paths, and moving `assertAgentAuthorized`
-below `resolveApproval` for convenience.