@pikku/core 0.12.143 → 0.12.144

package/knowledge/decisions/security/agent-sessionless-deployments-have-no-thread-ownership.md

@@ -1,39 +0,0 @@
----
-type: decision
-title: Agent thread ownership fails closed when there is no principal
-description: A sessionless caller gets an ephemeral owner and reaches no stored thread, rather than reaching all of them
-tags: agent
----
-
-# Agent thread ownership fails closed when there is no principal
-
-`canAccessThread` returns `false` and `threadOwnerConstraint` returns `[]` when
-the session carries neither `userId` nor `orgId`
-(`packages/core/src/wirings/agent/agent-prepare.ts`).
-`resolveOwnerResourceId` never accepts the client-supplied `resourceId` as an
-ownership key; without a principal it mints an ephemeral `anon-<uuid>` owner
-memoized on the request's params object.
-
-Agent wirings default to `auth: false`, so "no session" is the common case
-rather than an exotic one. Treating it as "no ownership model to enforce" made
-every ownership check vacuous: a caller named any `resourceId` and reached that
-thread, and because `undefined` on `AgentRunService.listThreads` means _no
-filter_ rather than _no rows_, a sessionless `getAgentThreads` returned every
-thread in the deployment. The ephemeral owner is what keeps one-shot
-conversations working while denying continuity — it is unguessable, so nothing
-stored can be reached, and it is stable within a request, so a sub-agent
-re-entering `resolveOwnerResourceId` reuses its parent's thread.
-
-Memoizing on the params object rather than a module-level Map is what keeps this
-serverless-safe: the identity dies with the request and is never shared between
-instances. `canAccessThread` stays a predicate rather than an assertion so it can
-back a `pikkuPermission` — authorization belongs in a function's `permissions`
-field, never in its body.
-
-**What this rules out:** returning `undefined` from `threadOwnerConstraint` for
-any caller; deriving `owners` from request input instead of the session; reading
-`auth: false` as permission to skip ownership on a _stored_ thread; and
-persisting the anonymous owner anywhere, which would turn an ephemeral identity
-into a forgeable one. Cross-request thread continuity without a session is not
-available by design — wire a session to get it back. See
-[[an-empty-owners-constraint-matches-nothing]].

package/knowledge/decisions/security/agent-thread-ownership-composes-the-session-principal.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: An agent thread key is always prefixed with the trusted principal
-description: Ownership keys are composed as principal:resourceId, so a client id can sub-divide its own boundary but never widen it
-tags: agent
----
-
-# An agent thread key is always prefixed with the trusted principal
-
-`resolveOwnerResourceId` in `packages/core/src/wirings/agent/agent-prepare.ts`
-composes the ownership key for a thread or run as `principal:resourceId`. The
-principal is the trusted one — `session.userId` for the default `'user'`
-`SessionScope`, `session.orgId` for `'org'` — and the client-supplied
-`resourceId` is only ever a sub-partition inside it. Composition is idempotent:
-a value already inside the caller's namespace (top-level re-entry, sub-agent
-recursion, resume — all of which pass an already-composite id) is returned
-unchanged rather than composed twice.
-
-`'org'` scope with no org on the session throws `ForbiddenError` instead of
-falling back to a bare or shared key, because a shared key leaks threads across
-organizations. A sessionless `'user'` wiring has no trusted principal at all and
-falls back to the requested `resourceId` as a best-effort partition.
-`isOwnedByPrincipal` requires the `:` separator when matching sub-partitions so
-that a principal `alice` does not match a lookalike `alice-evil:…` key.
-
-**What this rules out:** storing threads under the client's `resourceId`
-directly; making the composition non-idempotent (resume and sub-agent recursion
-would double-prefix and lose their own threads); testing ownership with a bare
-`startsWith(principal)` that omits the separator; and letting `'org'` scope
-degrade to a shared key when the session carries no organization.

package/knowledge/decisions/security/agent-tool-filtering-reads-the-live-function-config.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Agent tool permission filtering reads the live function config, not the metadata
-description: The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
-tags: agent
----
-
-# Agent tool permission filtering reads the live function config, not the metadata
-
-`buildToolDefs` in `packages/core/src/wirings/agent/agent-prepare.ts`
-decides which tools and sub-agents to expose to the model by calling
-`checkAuthPermissions` against the permission objects held in the live function
-(or agent) config in `pikkuState`, using the metadata only to learn that a
-permission exists at all.
-
-The `pikkuAuth` brand that marks a permission as an authorization gate exists
-only on those live objects. The metadata's by-name permission registry is never
-populated, so resolving names through it collects no predicates — and a filter
-that collects no predicates admits everything. The failure is silent: every gated
-tool would be handed to the model for any session.
-
-**What this rules out:** simplifying the filter to read
-`fnMeta.permissions` / `subMeta.permissions` directly, and caching a
-name-to-predicate map derived from metadata.

package/knowledge/decisions/security/an-addon-header-can-only-narrow-the-session.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: An addon header can only narrow the session, and an unknown addon is refused
-description: addon-scope-cap intersects the session's scopes with the named addon's role, so naming an addon never widens access, and a name the host does not know is a 403
-tags: core, middleware, scopes, addons
----
-
-# An addon header can only narrow the session, and an unknown addon is refused
-
-`packages/core/src/middleware/addon-scope-cap.ts` reads the `x-pikku-addon`
-header (`addon-scope-cap.ts:8`, `31`). When a session is present, it resolves
-the addon's role and replaces the session's scopes with
-`intersectScopes(session.scopes, role)` (`addon-scope-cap.ts:37-45`).
-
-The doc comment says the header "is a selector, not a credential: naming an
-addon can only reduce a session" (`addon-scope-cap.ts:16-17`). An addon the host
-does not know throws `ForbiddenError` (`addon-scope-cap.ts:38-40`), because the
-comment says ignoring it "would let a misspelt name run uncapped"
-(`addon-scope-cap.ts:18-19`).
-
-With no header, or no session, the middleware calls `next()` and changes
-nothing (`addon-scope-cap.ts:33-34`). The comment says to register it after the
-session middleware (`addon-scope-cap.ts:21-22`).
-
-**What this rules out:** using the header to gain scopes, and treating an
-unrecognised addon name as "no cap".

package/knowledge/decisions/security/an-addon-instance-reads-only-the-secrets-and-credentials-it-is-named.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: An addon instance reads only the secrets and credentials it is named
-description: An addon's secret and credential views are its declared names plus the consuming app's grants and override keys; the global flags opt out of scoping
-tags: core, addons, secrets, credentials
----
-
-# An addon instance reads only the secrets and credentials it is named
-
-The consuming app decides which secrets and credentials an addon instance may
-read. The grant fields are declared on the wiring as "set by the consuming app"
-(`packages/core/src/wirings/rpc/rpc-types.ts:73-76`) and carried through
-`wireAddon` (`packages/core/src/wirings/addon/wire-addon.ts:123-126`) into the
-instance (`packages/core/src/wirings/addon/addon-runner.ts:20-22`).
-
-The allowed set is built by `allowedNames` in `addon-runner.ts:40-49`: the names
-the package declared, plus the grants, plus the keys of the overrides. An
-override key therefore grants the name; the override value is the key the
-lookup is pointed at. `wire-addon.ts:71` says the grant check runs before
-`secretOverrides` rename a name.
-
-Scoping is applied when the instance's services are built
-(`addon-runner.ts:200-227`). Unless `globalSecrets` is set, the secret service
-is wrapped in `ScopedSecretService`; unless `globalCredentials` is set, the
-credential service is wrapped in `ScopedCredentialService`. The global options
-hand over the unscoped service, and their value is a reason string
-(`wire-addon.ts:75-82`). The comments say the reason is recorded in the deploy
-manifest; that recording was not traced here.
-
-**What this rules out:** an addon reading a name neither it declared nor the
-host named, including through an override value; and an unscoped service
-reaching an addon without the consuming app setting a `globalSecrets` or
-`globalCredentials` reason.

package/knowledge/decisions/security/an-addon-may-reach-only-itself-and-the-addons-it-uses.md

@@ -1,16 +0,0 @@
----
-type: decision
-title: An addon may reach only itself and the addons it declares in uses
-description: An RPC call that arrives tagged with an addon header is refused unless the target is the caller or one of the caller's declared uses, and an unknown addon name is refused outright
-tags: core, addons, rpc, scopes
----
-
-# An addon may reach only itself and the addons it declares in uses
-
-`addonMayReach` in `packages/core/src/wirings/addon/addon-reach.ts` takes the caller addon and the target function name (`addon-reach.ts:6`). It takes the target from the part of the name before `:` (`addon-reach.ts:7`). It returns `false` for an empty target (`:8`), `true` when the target is the caller (`:9`), and otherwise `true` only when the caller's declared `uses` includes the target (`:10-11`).
-
-`addonCallerOf` reads the addon header from the HTTP request (`addon-reach.ts:14-16`). A name that is not a registered addon is refused with `ForbiddenError` (`addon-reach.ts:17-18`).
-
-`ContextAwareRPCService.rpcExposed` applies the check before resolving the function. A caller that fails `addonMayReach` gets `AddonNotUsedError` (`packages/core/src/wirings/rpc/rpc-runner.ts:189-192`).
-
-**What this rules out:** an addon calling into another addon it does not declare in `uses`, and an addon header naming an unregistered addon being treated as anonymous rather than refused.

package/knowledge/decisions/security/an-agent-approval-is-claimed-before-the-tool-runs.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: An agent approval is claimed before the tool runs
-description: resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
-tags: agent
----
-
-# An agent approval is claimed before the tool runs
-
-Resuming a suspended agent run read the run, checked `status === 'suspended'`,
-snapshotted `pendingApprovals`, called `resolveApproval`, executed the tool, and
-only then wrote `status: 'running'`. Nothing spanned that sequence — no
-transaction, no row lock, no conditional update — so concurrent approvals of the
-same tool call all observed `suspended`, all snapshotted the same list, and all
-reached `execute`. `resolveApproval` returned `void`, so a loser could not even
-tell.
-
-`resolveApproval` is now the claim, and returns whether _this_ caller made it.
-The stores implement it as a compare-and-swap: Kysely updates the run row only
-while `status = 'suspended'` and `pendingApprovals` still equals the list it
-read; the tool-call stores move the row off `approvalStatus = 'pending'` and
-count the rows they changed. Both resume paths run the tool only for the ids they
-claimed, and a caller that claimed nothing gets an error rather than a silent
-re-run.
-
-The claim is per tool call, not per run, so concurrent approvals of _different_
-tool calls on one run all proceed — which is the case that made a run-level
-`claimSuspendedRun` the worse fit.
-
-**What this rules out:** treating `getRun` as a claim, adding a resume path that
-executes a tool without a `true` from `resolveApproval`, and implementing
-`resolveApproval` as a read-modify-write in any new store — the return value is
-a promise about atomicity, not a convenience.

package/knowledge/decisions/security/an-api-key-is-jwt-decoded-into-the-session.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: An API key is JWT-decoded into the session, from a header or a query parameter
-description: authAPIKey reads x-api-key or the apiKey query parameter, decodes it as a JWT, and sets the session only when no session exists yet
-tags: core, auth, middleware, api-keys
----
-
-# An API key is JWT-decoded into the session, from a header or a query parameter
-
-`packages/core/src/middleware/auth-apikey.ts` takes an API key from the
-`x-api-key` header, the `apiKey` query parameter, or both, depending on the
-`source` option (`auth-apikey.ts:11-13`, `21-27`). The header is tried first;
-the query is read only when no header value was found (`auth-apikey.ts:25`).
-
-The key is decoded with `jwtService.decode` and, if that returns a value, passed
-to `setSession` (`auth-apikey.ts:29-33`). The middleware does nothing when a
-session already exists (`auth-apikey.ts:17`), which the doc comment describes as
-leaving "an existing session alone, so it composes with other auth middleware"
-(`auth-apikey.ts:6-7`).
-
-Nothing is decoded when no `jwtService` is wired (`auth-apikey.ts:29`).
-
-**What this rules out:** an API key overriding a session that is already set,
-and a key being accepted without a JWT service to verify it. The code also
-accepts a key from the query string (`auth-apikey.ts:26`), so keys can appear in
-URLs when `source` includes `query`.

package/knowledge/decisions/security/an-approval-answer-outlives-the-run-it-answered.md

@@ -1,59 +0,0 @@
----
-type: decision
-title: An approval answer outlives the run it answered
-description: Run state holds a decision only while the gate is open, so the settled answer carries decidedBy/decidedAt into the step result and every attempt is written to the audit sink, which has no foreign key to the run
-tags: workflow, audit
----
-
-# An approval answer outlives the run it answered
-
-An approval gate is asked for so it can be answered for afterwards. "Who
-released the funds" is the entire point of four-eyes sign-off, and until this
-change none of it was kept.
-
-Run state is where a decision _waits_, not where it is kept. The record under
-`workflowRuns.state.__approval_<hex>` is overwritten by the next write to that
-key, and cleared outright — `decidedBy: undefined` included — whenever a
-decision is refused on replay. A trail that erases exactly the events worth
-keeping is not a trail.
-
-So the answer is recorded twice, in two places with different lifetimes.
-
-## The settled decision keeps its provenance
-
-`ApprovalOutcome<T>` carries `decidedBy` and `decidedAt` alongside `data`, so
-the answer reaches `workflowStep.result` and, through it,
-`workflowStepHistory` — append-only, and already the per-step event log. Both
-are spread in only when present, so a gate answered without a session keeps the
-shape it had before there was anything to record.
-
-## The audit sink is what survives deletion
-
-`deleteRun` cascades: `workflowStep` is `onDelete('cascade')` from
-`workflowRuns`, and `workflowStepHistory` from `workflowStep`. Deleting a run
-therefore deletes the sign-off with it — and a _refused_ attempt never reaches a
-step at all, so it was never in that trail to begin with.
-
-Every answer — accepted, refused at submission, or cleared on replay — is
-written to the `AuditService` as `workflow.approval.decided`, with
-`outcome: 'success' | 'denied'`, the decider under `userIdentity.pikkuUserId`,
-and the run, reason, scopes and refusal in `metadata`. The `audit` table holds
-no foreign key to any workflow table, which is precisely why it is the right
-home.
-
-`auditApprovalDecision`
-(`packages/core/src/wirings/workflow/workflow-approval-audit.ts`) is a module of
-its own rather than a method on `PikkuWorkflowService`: the trail is a separate
-concern from running the workflow, and the service is already at the 2000-line
-limit `source-files-stay-composable.test.ts` enforces.
-
-**A sink that fails is logged, never thrown.** The trail must not be the reason a
-decision is lost. A project with no `audit` service wired records nothing and is
-otherwise unaffected — the sink is opt-in, and `auditSchema` is deliberately not
-in `pikkuSchemas`.
-
-**What this rules out:** a dedicated `workflowApprovals` table. It would have to
-be implemented in all seven backends and would still be deleted with the run
-unless it deliberately broke the cascade — at which point it is the audit table
-with extra steps. If approvals later need to be _queried_ as a first-class
-entity rather than read back from the trail, that is when to revisit.

package/knowledge/decisions/security/an-empty-owners-constraint-matches-nothing.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: An empty owners constraint matches nothing
-description: owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
-tags: agent, storage
----
-
-# An empty owners constraint matches nothing
-
-Every `AgentRunService.listThreads` implementation returns `[]` immediately when
-`owners` is present and empty — `kysely-agent-run-service.ts`,
-`redis-agent-run-service.ts`, `mongodb-agent-run-service.ts`. The conformance
-suite in `packages/core/src/testing/service-tests.ts` pins it, so a new backend
-inherits the requirement instead of rediscovering it.
-
-`owners` is an authorization boundary, not an optional filter. The natural way
-to write a query builder is to skip a clause when its list is empty, which
-silently converts "this caller may see nothing" into "this caller may see
-everything" — the failure is invisible in review because the omitted clause
-looks like an optimization. Placing the guard before the query is built, in
-every backend, means the dangerous shape never exists.
-
-This is what makes the sessionless `[]` from `threadOwnerConstraint` safe to
-return; the two decisions only hold together.
-
-**What this rules out:** folding the empty case into the query builder's normal
-`if (owners)` path; treating `owners: []` as equivalent to `owners: undefined`
-at any layer; and adding a backend without the conformance suite.
-
-See [[agent-sessionless-deployments-have-no-thread-ownership]].

package/knowledge/decisions/security/an-exposed-ungated-function-is-a-codegen-warning.md

@@ -1,52 +0,0 @@
----
-type: decision
-title: An exposed function with no gate is reported at codegen, not at boot
-description: The check runs in the inspector where function meta and every wireAddon declaration are both in hand, because neither source alone can tell a gated function from an ungated one
-tags: authorization, inspector, addon, rpc
----
-
-# An exposed function with no gate is reported at codegen, not at boot
-
-The generated `POST /rpc/:rpcName` dispatcher forwards to `rpc.exposed`, which
-refuses anything without `expose: true`. That makes the reachable set small and
-deliberate — someone typed it. What it does not do is check whether the target
-is gated, because a dispatcher cannot know what it is dispatching to. The
-console shipped ~54 privileged functions through exactly this gap, and nothing
-in the toolchain said so.
-
-The check belongs next to `validateAuthSessionless`, in the inspector, for one
-reason: it needs two sources that only meet there.
-
-`sessionless` records the baseline — a `pikkuFunc` always requires a session —
-but a `pikkuSessionlessFunc` may still tighten itself with `auth: true`, which
-the inspector previously discarded. It is now recorded on function meta, so
-"sessionless and ungated" is distinguishable from "sessionless and
-self-gated" without running anything.
-
-The second source is `wireAddon`. Its `scopes` and `auth` apply to every
-function in the package on every wiring path (see
-[addon scopes](./addon-scopes-are-resolved-where-the-function-runs.md)), so a
-function with no gate of its own may still be fully covered. The inspector
-already parsed `wireAddon` for its endpoint and its secret, variable and
-credential overrides, and dropped `scopes`, `auth` and `tags` — the addon's
-plumbing was recorded in full and its authorization was not. Reading function
-meta alone would have reported every console function as open.
-
-An addon whose gates are not statically knowable — a spread, a const reference —
-is recorded as absent, and absent is read as **gated**. This is deliberately the
-wrong way round from how a runtime gate fails: a false negative costs one
-missing warning, while a false positive on a correctly-secured addon costs
-confidence in every warning the tool emits, which is worth more than the one
-case it would catch.
-
-Severity is `warn`, not `critical`. `expose: true` on an ungated sessionless
-function is legitimate for a genuinely public endpoint — a health check, a
-sign-up — so this cannot block a build without breaking correct programs. It
-fails a build only under `--fail-on-warn`. And the public endpoint is not left
-warning forever: an explicit `auth: false` on a sessionless function declares it
-public on purpose and silences the check (see
-[public is declared with auth: false](./a-public-function-says-so-with-auth-false.md)).
-
-**What this rules out:** checking at boot, where the report arrives after
-deployment; checking in `pikku validate` from `.pikku` JSON, which does not
-carry `wireAddon` at all; and treating an unparseable addon gate as no gate.

package/knowledge/decisions/security/an-external-virtual-user-caller-presents-one-signed-statement.md

@@ -1,38 +0,0 @@
----
-type: decision
-title: An external virtual user caller presents one signed statement
-description: Callers outside the app sign an EdDSA statement naming the virtual user; the app verifies it against a public key and accepts each statement once
-tags: services
----
-
-# An external virtual user caller presents one signed statement
-
-The statement is an EdDSA (Ed25519) JWT: `sub` is the virtual user id, `aud` is the
-app's origin, `iat`, `exp` a few minutes out (default 180 seconds, ceiling 300), and
-`jti`, a one-time id. The CLI signs it with `node:crypto`; the app verifies it with
-`JoseVirtualUserStatementVerifier` (`packages/services/jose`), `jwtVerify` pinned to
-`algorithms: ['EdDSA']`, against a public key. `POST /sign-in/virtual-user` takes
-`{ statement }`, maps `sub` to a declared virtual user, and signs it in.
-
-It is rejected for a wrong algorithm (`none` and HS256 included), a wrong key, a wrong
-audience, expiry, a lifetime beyond the ceiling, a missing `sub` or `jti`, and a `jti`
-already accepted. The replay store is a per-process map of `jti` to expiry, purged on
-each call, so it never outgrows the last few minutes of statements.
-
-One statement replaces three older credentials — a secret derived per virtual user from
-a root, an operator token with impersonation, and an app-wired sign-in hook — because
-each of them put something the app could mint a session from in the hands of a caller,
-or in the app's own configuration. A public key lets the app check a statement and
-nothing else; capturing the app's environment yields no ability to sign one.
-
-The **id-only dev switcher** (`/sign-in/switch-virtual-user`) is unchanged under
-`pikku dev`. Anywhere else it also needs a `statement` naming the same id, so no
-deployed stage has a credential-free way in.
-
-The statement endpoint needs the declared virtual users to map an id to an address, so
-it is registered only when the app passes `virtualUserSignIn.virtualUsers`, which the
-generated `virtualUserList` supplies.
-
-**What this rules out:** the app holding a private key, a statement without an
-expiry or one-time id, an algorithm negotiated by the token, and a switcher that works
-on a stage without proof.

package/knowledge/decisions/security/an-inbound-webhook-source-dispatches-only-verified-requests.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: An inbound webhook source dispatches only requests verified against its credential
-description: A webhook source with verify refuses a body-carrying request that fails its check, fails closed on an empty secret, and does not dispatch events from a body-less request
-tags: core, webhooks, trigger, security
----
-
-# An inbound webhook source dispatches only requests verified against its credential
-
-`verifyRequest` in `packages/core/src/wirings/trigger/webhook-source-runner.ts:173-200`
-decides whether a request counts as signed. A source with no `verify` returns
-true (`:178`). Otherwise the secret is read from the credential named by
-`source.credential`, or from `webhookSecretCredentialName` (`:180-182`).
-
-When the secret is missing or empty, a body-less request is treated as
-unverified (`:184`), and a request with a body throws `UnauthorizedError`
-(`:185-187`). `signedWith` also fails closed on an empty secret (`:127-128`).
-The token form compares with `timingSafeStringEqual` (`:153-155`), which is
-defined in `packages/core/src/utils/hmac.ts:57-63`.
-
-A mismatch on a request with a body throws (`:199`). A body-less request is not
-an error, but the runner refuses any events it produces: if `verified` is false
-and `receive` returned events, it throws `UnauthorizedError` (`:273-276`). The
-same contract is documented for authors at
-`packages/core/src/wirings/trigger/webhook-source.types.ts:130-135`, and the
-helper that runs the source's steps calls `runPikkuFunc` with `auth: false`
-(`webhook-source-runner.ts:96-101`), so the signature, not a session, is the
-gate.
-
-**What this rules out:** dispatching events from a body-carrying request that did
-not verify, and treating an empty signing secret as a valid key.

package/knowledge/decisions/security/an-mcp-call-with-no-http-request-stays-anonymous.md

@@ -1,18 +0,0 @@
----
-type: decision
-title: An MCP call with no HTTP request stays anonymous by transport design
-description: MCP calls that arrive without an HTTP request, such as stdio, reach the function with no session because auth middleware reads the session only from the request
-tags: core, mcp, auth, transport
----
-
-# An MCP call with no HTTP request stays anonymous by transport design
-
-`RunMCPEndpointParams.http` in `packages/core/src/wirings/mcp/mcp-runner.ts` is the HTTP request an MCP call arrived on (`mcp-runner.ts:39-41`, field at `:52`).
-
-The comment gives the mechanism. Auth middleware reads the session off `wire.http.request`, and every implementation returns early when there is no request (`mcp-runner.ts:42-46`). Without the request, an MCP call reaches the function unauthenticated whatever middleware is registered (`mcp-runner.ts:43-46`).
-
-The field is left undefined for transports with no request, such as stdio. The comment says those calls remain anonymous, and that this is a property of the transport rather than a default chosen in the runner (`mcp-runner.ts:48-50`).
-
-The surrounding decision about sessionless MCP entry points is in [MCP resources, tools and prompts take sessionless functions](mcp-resources-tools-and-prompts-take-sessionless-functions.md). The refusal for an HTTP call that needs a session is in [an MCP refusal is decided before dispatch](an-mcp-refusal-is-decided-before-dispatch.md).
-
-**What this rules out:** treating a request-less MCP call as carrying a session, and filling in a fake HTTP request to make middleware run for a stdio caller.

package/knowledge/decisions/security/an-mcp-refusal-is-decided-before-dispatch.md

@@ -1,48 +0,0 @@
----
-type: decision
-title: An MCP refusal is decided before dispatch, not raised from the tool
-description: mcpTargetRequiresSession lets the transport answer 401 with an OAuth challenge, because the MCP response streams and the status is gone by the time the runner refuses
-tags: mcp, permissions, transport
----
-
-# An MCP refusal is decided before dispatch, not raised from the tool
-
-An MCP client discovers how to authenticate from a `401` carrying a
-`WWW-Authenticate` challenge — that header names the RFC 9728 Protected Resource
-Metadata document, which names the authorization server, which is where OAuth
-starts. Delivered any other way, the refusal is not a refusal: a `MissingSessionError`
-flattened into a JSON-RPC result arrives as `200` with `isError: true`, which a
-client reads as a tool that failed, and no discovery happens.
-
-The obvious implementation — catch the refusal in `tools/call` and set the status
-afterwards — cannot work, and not for a reason a test makes obvious. The MCP HTTP
-response **streams**: the entry returns a `Response` whose body the transport is
-still writing when the JSON-RPC handler runs. Instrumenting both ends shows the
-entry observing its own flag as unset *before* the tool ever refuses. Status and
-headers are chosen at the top of the response; by the time anything knows a
-session was missing, they are already on the wire.
-
-So the decision moves earlier, to the only two things knowable before dispatch:
-which target the request body names, and whether the request presents anything to
-authenticate with. `mcpTargetRequiresSession` answers the first from the same
-declarations the runner enforces — a `pikkuFunc` always needs a session, a
-`pikkuSessionlessFunc` needs one only where it says `auth: true` — so the
-transport's answer and the runner's cannot disagree. An unregistered name is
-treated as open, because a name nobody registered is a `Method not found`, and
-challenging it invites a client to authenticate its way towards a tool that does
-not exist.
-
-This is what makes a single endpoint serve public and private tools together,
-which the MCP spec allows and pikku's per-function `auth` flag already describes.
-`tools/list` stays ungated, so a client can see the menu before it has a token.
-
-**What this rules out:** verifying tokens in the transport. Only a request with
-*no* credentials is challenged; a present-but-expired token is dispatched and its
-refusal reaches the client as a tool error. Doing better means resolving the
-session before dispatch, which runs the app's middleware twice per call and puts
-the transport in the business of second-guessing the middleware that owns session
-resolution. The cheaper half — no credentials at all — covers the case that
-actually matters, because that is the state every client starts in.
-
-Also ruled out: gating the endpoint as a whole with `requireBearerAuth`. It would
-work, and it would make every public tool private, which is a different product.

package/knowledge/decisions/security/an-oauth2-credential-is-read-by-its-account-row.md

@@ -1,40 +0,0 @@
----
-type: decision
-title: An OAuth2 credential is read by its account row, not by its provider name
-description: better-auth 1.7.5 selects an account by row id under a strict body schema, so BetterAuthCredentialService resolves the row through the internal adapter before asking for a token
-tags: better-auth, credentials, oauth2
----
-
-# An OAuth2 credential is read by its account row, not by its provider name
-
-A pikku OAuth2 credential is named — `user-oauth`, `company-slack` — and that
-name is the better-auth `providerId` its account row carries. Reading the
-credential used to mean handing better-auth the name:
-`getAccessToken({ body: { providerId, userId } })`.
-
-better-auth 1.7.5 stopped accepting that. `get-access-token` and
-`unlink-account` both take a strict union selecting the account by its **own row
-id**, so a provider name is not merely ignored, it is rejected — `[body] Invalid
-input`, a 500 on every read of a linked credential: a tool's token, an agent's,
-the console's status card. An agent that cannot resolve its credential never
-makes a model call, so the failure surfaces far from its cause.
-
-So the name is resolved to a row first, through
-`context.internalAdapter.findAccounts(userId)` — the same lookup the link
-callback writes the row with and `unlinkAccount` already used. That is also the
-only account lookup that takes a userId at all: `listUserAccounts` resolves the
-*caller's session* and throws UNAUTHORIZED server-side, which is no use for the
-two revocations that have no session — a platform credential, whose owner never
-signs in, and an admin acting on someone else's.
-
-A useful consequence: an unlinked provider is now answered before better-auth is
-asked, rather than by catching its `ACCOUNT_NOT_FOUND`. The catch stays, because
-a failed refresh must still not read as "not connected yet" — that would show a
-connect button for an account that is linked but broken.
-
-**What this rules out:** treating `providerId` as a credential's address
-anywhere a token is read or revoked. It remains the credential's *name* — what
-an app declares and what the link flow writes — but the row id is what
-better-auth is spoken to in. A fake of better-auth that keys tokens by provider
-name will pass while the real thing rejects every call, which is how this
-survived a bump with 222 green unit tests behind it.

package/knowledge/decisions/security/an-omitted-user-id-addresses-the-platform-credential.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: An omitted userId on CredentialService addresses the platform credential
-description: The CredentialService contract reads and writes the platform-level credential whenever a per-credential call omits userId, and the better-auth implementation defaults its platform owner to pikku-platform
-tags: core, credentials, security, interface
----
-
-# An omitted userId on CredentialService addresses the platform credential
-
-`CredentialService` in `packages/core/src/services/credential-service.ts` is the store for dynamic
-credentials such as OAuth tokens and per-user keys. Its doc comment says that throughout the interface,
-an omitted `userId` means the platform-level credential (`packages/core/src/services/credential-service.ts:4`).
-
-The per-credential methods take an optional `userId`: `get` (`credential-service.ts:7`), `set` (`:9`),
-`delete` (`:11`) and `has` (`:13`). Omitting it selects the platform credential, so the caller chooses
-the identity by whether it passes one.
-
-The methods that enumerate users are different. `getAll` requires `userId` (`credential-service.ts:15`),
-and `getUsersWithCredential` and `getAllUsers` take a credential name or nothing
-(`credential-service.ts:17` and `:19`). They do not have a platform default.
-
-The better-auth implementation applies the platform default only to some credentials. It takes an optional
-`platformUserId` that falls back to `PLATFORM_USER_ID` (`packages/services/better-auth/src/better-auth-credential.service.ts:58`).
-Its owner lookup returns null for a name that is not an OAuth2 credential (`better-auth-credential.service.ts:69-70`),
-returns that platform owner only for a singleton OAuth2 name (`better-auth-credential.service.ts:72-73`),
-and otherwise returns the `userId` passed in, or null when none was passed (`better-auth-credential.service.ts:75`).
-So for a non-singleton credential, an omitted `userId` reads as no owner, not as the platform credential. The
-interface comment describes the platform case more widely than this implementation does. Who may link the
-singleton is covered by [a singleton credential belongs to a reserved platform user](../../../../services/better-auth/knowledge/decisions/a-singleton-credential-belongs-to-a-reserved-platform-user.md).
-
-**What this rules out:** a sentinel string or an empty value to mean the platform credential, and relying on an
-omitted `userId` to reach the platform credential for a credential that is not a singleton.

package/knowledge/decisions/security/an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: An upload is counted as it arrives, not buffered and then measured
-description: Reading the whole body before checking its size hands an unauthenticated caller a way to spend the server's memory
-tags: core, content
----
-
-# An upload is counted as it arrives, not buffered and then measured
-
-The local content request handler accumulates the request body chunk by chunk,
-tracking the running total, and abandons the read the moment it crosses the
-limit. An oversized upload therefore costs the limit, not its own size.
-
-The obvious alternative — `await request.arrayBuffer()` and then check
-`byteLength` — has to hold the entire body in memory before it can decide the
-body is too large. For an endpoint reachable before authentication that is a
-way to spend the server's memory for the price of one request, and no size limit
-configured anywhere prevents it.
-
-`readRequestBody` in the node HTTP server aborts on the same terms, for the same
-reason.
-
-**What this rules out:** replacing the streaming accumulation with a single
-buffered read because the limit check "still happens".