@pikku/core 0.12.72 → 0.12.77

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

@@ -0,0 +1,31 @@
+---
+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: ai-agent
+---
+
+# An agent requires a session only when auth is true, but always enforces scopes and permissions
+
+`assertAgentAuthorized` in
+`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` enforces, in order:
+session presence (only when `CoreAIAgent.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-types.gen.ts`, 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/ai-agent-ownership-failures-never-echo-the-resource.md

@@ -0,0 +1,23 @@
+---
+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: ai-agent
+---
+
+# An agent ownership failure never echoes the resource it refused
+
+`assertResourceOwner` in
+`packages/core/src/wirings/ai-agent/ai-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/ai-agent-resume-re-runs-the-authorization-gate.md

@@ -0,0 +1,22 @@
+---
+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: ai-agent
+---
+
+# Resuming a suspended agent run re-runs the agent's authorization gate
+
+Both `resumeAIAgent` (`ai-agent-stream.ts`) and `resumeAIAgentSync`
+(`ai-agent-runner.ts`) call `assertAgentAuthorized` after asserting run
+ownership and before touching `aiRunState.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.

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

@@ -0,0 +1,39 @@
+---
+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: ai-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/ai-agent/ai-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/ai-agent-thread-ownership-composes-the-session-principal.md

@@ -0,0 +1,30 @@
+---
+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: ai-agent
+---
+
+# An agent thread key is always prefixed with the trusted principal
+
+`resolveOwnerResourceId` in `packages/core/src/wirings/ai-agent/ai-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/ai-agent-tool-filtering-reads-the-live-function-config.md

@@ -0,0 +1,24 @@
+---
+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: ai-agent
+---
+
+# Agent tool permission filtering reads the live function config, not the metadata
+
+`buildToolDefs` in `packages/core/src/wirings/ai-agent/ai-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-empty-owners-constraint-matches-nothing.md

@@ -0,0 +1,30 @@
+---
+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: ai-agent, storage
+---
+
+# An empty owners constraint matches nothing
+
+Every `AgentRunService.listThreads` implementation returns `[]` immediately when
+`owners` is present and empty — `kysely-ai-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 [[ai-agent-sessionless-deployments-have-no-thread-ownership]].

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

@@ -0,0 +1,49 @@
+---
+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`.
+
+**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/console-addon-privileged-functions-gate-themselves.md

@@ -0,0 +1,76 @@
+---
+type: decision
+title: The console addon's privileged functions gate themselves
+description: Thread listing is owner-scoped unless the caller holds admin, and addon installation requires an admin session, rather than trusting the host to register a global permission
+tags: addon, ai-agent, rpc
+---
+
+# The console addon's privileged functions gate themselves
+
+`@pikku/addon-console` is wired into the consuming application by the generated
+`console.gen.ts` that `scaffold.console` produces — `wireAddon({ name:
+'console', package: '@pikku/addon-console' })`. That file is compiled into the
+app and ships wherever the app ships, so every `expose: true` console function
+is reachable over the app's own `POST /rpc/:rpcName` route in production, not
+only from `pikku dev`. `pikku serve --console` binds `127.0.0.1` and adds a
+static SPA mount; it wires no functions. The console UI being a development tool
+is a convention about who opens the browser tab; it is not a deployment
+boundary.
+
+The transport in front of that route is configured separately from the console:
+`scaffold.rpc` defaults to `"no-auth"` in `templates/functions/pikku.config.json`
+and in `e2e/pikku.config.json`, which generates `wireHTTP({ route:
+'/rpc/:rpcName', auth: false })`. `scaffold.console: "auth"` does not raise it,
+and the generated `wireAddon` carries no `auth` key, so `addonConfig.auth` is
+undefined at the addon boundary too. The remaining session check is the function
+runner's, which for a `pikkuSessionlessFunc` fires only when the function itself
+sets `auth: true`.
+
+The addon's original authorization story was a single package-scoped
+`addGlobalPermission([isAdmin], '@pikku/addon-console')` that the *host*
+registered, which `runPermissions` resolves in the callee's package namespace and
+applies to every function at once. Nothing generated that call — the scaffold
+emitted only a comment recommending it, and `resolveGlobalPermissions` returns an
+empty list when the host registered none, which `runPermissions` treats as
+allow. An app that followed the scaffold and stopped there had a fully open
+console surface. The scaffold now emits `wireAddon({ …, scopes: ['admin'] })`
+instead, which the function runner enforces on every function in the package.
+
+The two functions whose failure mode is worst still do not depend on any
+package-wide gate:
+
+`getAgentThreads` derives `owners` from the session with core's
+`threadOwnerConstraint` and passes it on every call, omitting it only when the
+session holds the `admin` scope root — listing every thread is the legitimate
+purpose of an admin console, and `hasScopes` accepts the umbrella grant and its
+wildcards. The `owners` value is never read from input, so a caller cannot name
+someone else's principal. A session with no principal yields `[]`, which every
+storage backend already treats as no rows.
+
+`installAddon` and `installOpenapiAddon` run a package manager against an
+attacker-chosen package name and write a wiring file into the project. They were
+`pikkuSessionlessFunc` with `auth: false`, which — behind a `no-auth` RPC route
+and with no host global permission — meant an unauthenticated POST reached
+`execFileSync`. They now declare `auth: true` and `scopes: ['admin']`, enforced
+by `verifyScopes` in the function runner before the body runs. Both gates are
+checked whether or not the host registered a global permission, and whether or
+not the addon itself was wired with scopes — an app that hand-wires
+`wireAddon({ name: 'console', package: '@pikku/addon-console' })` without them
+still cannot reach `execFileSync` unauthenticated.
+
+`admin` is spelled as a literal here because it is a scope id in the addon's own
+`wireScope` tree, the same tree the `pikku:scopes:*` gates on the scope-admin
+functions come from.
+
+**What this rules out:** treating the host's `addGlobalPermission` as the only
+gate in front of an operation that installs code or reads another principal's
+data; deriving `owners` from request input; returning `owners: undefined` for a
+caller who simply has no principal; and gating these functions on a
+`metaService.basePath` check — that is a filesystem-availability test which the
+generated `PikkuMetaService` satisfies in any unbundled Node deployment, not an
+is-this-localhost test.
+
+See [[addon-scopes-are-resolved-where-the-function-runs]],
+[[an-empty-owners-constraint-matches-nothing]],
+[[ai-agent-sessionless-deployments-have-no-thread-ownership]] and
+[[global-permissions-and-function-permissions-are-independent-gates]].

package/knowledge/decisions/security/core-safe-fetch-blocks-ssrf-by-host-literal-not-dns.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: Core's SSRF guard matches host literals because edge runtimes have no DNS
+description: safeFetch rejects internal address literals and re-validates every redirect hop; it cannot stop DNS rebinding
+tags: core
+---
+
+# Core's SSRF guard matches host literals because edge runtimes have no DNS
+
+`packages/core/src/utils/safe-fetch.ts` guards every outbound fetch that core
+makes on a caller-supplied URL. `@pikku/core` runs in edge runtimes (Cloudflare
+Workers) that have no Node `dns` module, so the guard cannot resolve a hostname
+and inspect the resulting address. It instead rejects address *literals* that are
+obviously internal — loopback, `10/8`, `172.16/12`, `192.168/16`, `0.0.0.0/8`,
+link-local `169.254/16` (the cloud metadata endpoint), IPv6 `::`, `::1`,
+`fe80::/10` and `fc00::/7` — plus the alias forms that reach the same targets:
+trailing-dot FQDNs, the reserved `*.localhost` names, IPv4-mapped IPv6, and the
+`inet_aton`-style octal/hex/32-bit-integer encodings that `fetch` and `undici`
+accept (`0177.0.0.1`, `0x7f000001`, `2130706433`).
+
+Literal matching alone is not enough, because the classic bypass is a public URL
+that 302s to `169.254.169.254`. So `safeFetch` sets `redirect: 'manual'` and
+re-validates every hop through `assertFetchableUrl` before following it, follows
+only the statuses in `REDIRECT_STATUSES` (301/302/303/307/308 — `300`, `304`,
+`305` and `306` are returned to the caller as-is), applies the WHATWG
+method/body transform per hop, cancels each intermediate response body, and
+strips `Authorization` and `Cookie` whenever a hop crosses origin. What it
+deliberately does **not** cover is DNS rebinding: a public hostname that itself
+resolves to a private IP passes, because catching that needs resolution the
+runtime does not offer.
+
+**What this rules out:** "simplifying" `isPrivateHost` down to a `localhost` /
+`127.0.0.1` string check — the octal, hex, integer and IPv4-mapped-IPv6 branches
+are each a live bypass, not defensive noise. It equally rules out replacing the
+manual redirect loop with `redirect: 'follow'` to shorten the function: the
+platform would then follow a `Location` into the internal network with no
+validation and no credential stripping, which is the entire attack this file
+exists to block. Do not add DNS-based checks either without gating them —
+importing `node:dns` breaks the Workers build.

package/knowledge/decisions/security/core-secrets-use-a-per-secret-dek-wrapped-by-a-kek.md

@@ -0,0 +1,37 @@
+---
+type: decision
+title: Core secrets are encrypted with a per-secret DEK wrapped by a KEK
+description: Envelope encryption keeps ciphertext untouched during key rotation, at the cost of storing two blobs per secret
+tags: core
+---
+
+# Core secrets are encrypted with a per-secret DEK wrapped by a KEK
+
+`packages/core/src/crypto-utils.ts` exposes two layers. `encryptJSON` /
+`decryptJSON` are the direct layer: a passphrase is hashed to an AES-GCM key and
+the output is `base64url(iv || ciphertext)` with a 12-byte IV. On top of that sit
+`envelopeEncrypt`, `envelopeDecrypt` and `envelopeRewrap`, which give every stored
+secret its own random 32-byte DEK (data encryption key). The secret is encrypted
+with the DEK; the DEK is then encrypted with a KEK (key encryption key) — in
+practice an environment variable or platform secret — and the pair
+`{ ciphertext, wrappedDEK }` is what gets persisted.
+
+The split exists so that rotating the KEK is cheap and non-destructive.
+`envelopeRewrap` unwraps the DEK under the old KEK and re-wraps it under the new
+one; the ciphertext of the secret itself is never read, never re-encrypted, and
+never re-written. A store holding a million secrets rotates by touching a million
+short blobs rather than re-encrypting every payload, and a rotation that fails
+part-way leaves both halves independently decryptable by whichever KEK still
+wraps them. The `keyVersion` / `previousKey` / `rotateKEK` shape that
+`ServiceTestConfig` requires of every `SecretService` and `CredentialService`
+implementation (`packages/core/src/testing/service-tests.ts`) is the storage-side
+contract that falls out of this.
+
+**What this rules out:** collapsing the envelope back to a single
+`encryptJSON(kek, secret)` call, or deriving the DEK from the KEK rather than
+generating it randomly. Either change makes the ciphertext depend on the KEK, so
+rotation becomes a full re-encrypt of every stored secret and `envelopeRewrap`
+stops being correct. It also rules out changing the `iv || ciphertext` layout or
+the 12-byte IV length in either layer — the length is hard-coded on the decrypt
+side (`data.slice(0, 12)`, minimum length 13), so any change silently fails to
+read every previously stored value.

package/knowledge/decisions/security/gateway-handlers-run-through-the-function-runner-gate.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: Gateway handlers run through the function runner gate
+description: A gateway's handler is registered as a real pikku function and invoked via runPikkuFunc, because calling it directly skips auth, scopes and permissions
+tags: gateway
+---
+
+# Gateway handlers run through the function runner gate
+
+`registerGatewayHandler` in
+`packages/core/src/wirings/gateway/gateway-runner.ts` registers `config.func`
+under a synthetic function id (`gateway__<name>__handler`) and every transport —
+webhook POST, websocket message, listener callback — invokes it via
+`runPikkuFunc`. This looks like an unnecessary indirection: the handler is right
+there in the config and could be awaited directly. It cannot. The function
+runner's gate is the only thing that evaluates a function's declared `auth`,
+`scopes` and `permissions`; a direct call runs the handler with none of them
+checked.
+
+The handler is registered with `sessionless: true`. Gateway inbound traffic is
+authenticated by the platform adapter (webhook signature verification, platform
+tokens), not by a user session, so defaulting to session-required would reject
+every legitimate webhook. `CoreGateway.auth` and the handler's own `auth: true`
+opt back into requiring a session. `scopes` and `permissions` are enforced
+whenever declared, session or not.
+
+**What this rules out:** invoking `config.func` directly from any gateway
+transport as an optimisation, and "simplifying" the synthetic function
+registration away. It also rules out flipping the sessionless default to
+session-required as a hardening measure — that breaks every webhook rather than
+securing it; require auth per gateway via `CoreGateway.auth` instead.

package/knowledge/decisions/security/gateway-middleware-sessions-must-be-bridged-onto-the-wire.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: Gateway middleware sessions must be bridged onto the wire
+description: Gateway middleware calling wire.setSession writes to a session service the handler's invocation never reads, so the session is copied onto wire.session before the gate runs
+tags: gateway
+---
+
+# Gateway middleware sessions must be bridged onto the wire
+
+`bridgeMiddlewareSession` in
+`packages/core/src/wirings/gateway/gateway-runner.ts` runs immediately before
+every `runPikkuFunc` call in the gateway runner, copying `await wire.getSession()`
+onto `wire.session` when the latter is unset. Gateway middleware is the only
+place a webhook can acquire a session at all — typically by mapping a verified
+platform sender id to a user. Middleware that assigns `wire.session` directly
+needs no help, but the idiomatic `wire.setSession()` writes into the *enclosing
+wiring's* session service, and the handler's own invocation does not read that
+service.
+
+Without the bridge, the failure mode is silent and it fails open in the way that
+matters: `auth` and `scopes` on the handler see no session, so a gateway whose
+middleware successfully authenticated the sender still evaluates its gate as
+unauthenticated. Nothing throws; the session is simply invisible.
+
+**What this rules out:** removing the `bridgeMiddlewareSession` call from any of
+the three transports (webhook POST, websocket message, listener) on the grounds
+that middleware "already set the session", and adding a fourth gateway transport
+that calls `runPikkuFunc` without bridging first. It also rules out relying on
+`wire.setSession()` alone anywhere the callee is a separately-registered pikku
+function.

package/knowledge/decisions/security/global-permissions-and-function-permissions-are-independent-gates.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: Global permissions and function permissions are independent gates
+description: Globals AND together and can only narrow access; a function's own group ORs internally and is never satisfied by a global
+tags: permissions
+---
+
+# Global permissions and function permissions are independent gates
+
+`runPermissions` in `packages/core/src/permissions.ts` runs two gates and both
+must pass. Every requirement registered through `addGlobalPermission` is checked
+in turn and any failure throws `ForbiddenError` — globals AND, so a global can
+only ever narrow access, never grant it. The function's own `permissions` group
+is then evaluated by `verifyPermissions`, which ORs the group's branches and ANDs
+the entries within a branch: the group passes if at least one branch is
+satisfied.
+
+That OR inside `verifyPermissions` is the only OR in authorization. Everything
+cross-cutting — globals, scopes, auth — ANDs. A function's own group is the sole
+place where "owner OR admin"-style alternatives belong. Crucially, a global that
+passed contributes nothing to the function gate: a broad `signedIn` global cannot
+satisfy an admin-only function's requirements, because the two gates are
+evaluated independently against separate inputs. An empty or absent group passes,
+so declaring no permissions means "globals only", not "deny".
+
+Globals are bucketed per package, and a function reads *both* the root bucket and
+its own package's — root first. The generated `addGlobalPermission` wrapper takes
+no package argument, so an application's rules only ever land in the root bucket;
+resolving the package bucket alone meant a host rule like "every request needs a
+signed-in user" silently stopped at the addon boundary, while the bucket an
+addon's functions actually read was one no host could write to. Unioning is safe
+in a way that nothing else here would be: globals AND, so adding the root ones
+can only tighten. Package buckets stay one-way — a package's globals never apply
+to root functions, or an installed addon could gate the whole application.
+
+**What this rules out:** short-circuiting the function gate when the globals
+passed, merging the global requirements into the function group (which would turn
+AND into OR and let any global satisfy any function), and giving
+`verifyPermissions` AND-across-branches semantics to "make it consistent" with
+the global gate.

package/knowledge/decisions/security/http-error-detail-is-withheld-from-clients-in-production.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: HTTP error detail is withheld from clients in production
+description: 5xx bodies carry only a trace id in production; exposeErrors can widen that in development but never in production
+tags: http
+---
+
+# HTTP error detail is withheld from clients in production
+
+`fetchData` in `packages/core/src/wirings/http/http-runner.ts` defaults
+`exposeErrors` to `!isProduction()`, and `handleHTTPError` in
+`packages/core/src/handle-error.ts` computes `clientFacing` as
+`errorResponse.status < 500 || (exposeErrors && !isProduction())`. Registered
+errors below 500 always return their own message and `payload`, because they
+describe something the caller did. Anything 500 and above returns only the
+registered generic message and the `errorId` trace id; the original `e.message`,
+`e.stack` and `payload` are dropped. The unregistered-error path is stricter
+still — it emits `{ errorId }` alone and attaches `message`/`stack` only when
+`exposeErrors && !isProduction()`.
+
+Unexpected 5xx messages are the ones that leak: driver errors carrying
+connection strings, ORM errors quoting rows, assertion text naming internal
+services. The trace id is the deliberate substitute — the operator correlates it
+with the logged error, which does carry the full message.
+
+Note the double gate. `exposeErrors` is re-checked against `isProduction()`
+inside `handleHTTPError` even though its default already accounts for it, so a
+runtime that passes `exposeErrors: true` explicitly still cannot open up a
+production deployment.
+
+**What this rules out:** collapsing the two `isProduction()` checks into the
+default value, letting a caller-supplied `exposeErrors` win in production, and
+"improving" the 5xx body by echoing `e.message` unconditionally.

package/knowledge/decisions/security/http-request-bodies-are-bounded-before-they-are-buffered.md

@@ -0,0 +1,46 @@
+---
+type: decision
+title: HTTP request bodies are bounded before they are buffered
+description: Content-Length is rejected up front and the stream is measured as it arrives, because that header is optional and attacker-controlled
+tags: http
+---
+
+# HTTP request bodies are bounded before they are buffered
+
+`PikkuFetchHTTPRequest.#readBoundedBuffer` in
+`packages/core/src/wirings/http/pikku-fetch-http-request.ts` enforces
+`maxBodySize` twice. A declared `content-length` above the limit is rejected
+before a single byte is transferred, which is the cheap path. The body stream is
+then measured chunk by chunk anyway, cancelling the reader and throwing
+`PayloadTooLargeError` the moment the running total crosses the limit — because
+`content-length` is optional (chunked encoding omits it) and, when present, is
+whatever the client chose to write. Trusting it alone would let a request declare
+1 KB and stream a gigabyte.
+
+`DEFAULT_MAX_BODY_SIZE` is 10 MB: ample for JSON APIs and ordinary uploads while
+keeping one request's memory footprint bounded, since the whole body is
+materialised in memory.
+
+Every adapter enforces the same limit and the same `PayloadTooLargeError`, but
+they divide into two kinds, and the difference is what can actually be
+prevented rather than merely reported:
+
+- **Prevention.** uWebSockets drives `res.onData` itself, so it counts bytes and
+  *drops* chunks past the limit rather than concatenating, replying 413 before
+  routing — the only point at which the buffering can be stopped, which is why
+  it deviates from the fetch adapter's 404-an-unmatched-route order. Fastify
+  delegates to native `bodyLimit`, set only when `maxBodySize` is configured so
+  the default never *loosens* fastify's stricter 1 MB. `PikkuExpressServer`
+  feeds the limit into `express.json`/`text`/`urlencoded`.
+- **Rejection only.** `express-middleware` is handed an already-parsed body, so
+  its guard makes the rejection uniform but cannot reclaim the memory; a
+  deployment mounting it on its own app must bound its own parser. Next server
+  actions receive a decoded JS value with no wire size left to measure — the
+  limit there is `experimental.serverActions.bodySizeLimit`.
+
+**What this rules out:** dropping the streaming measurement once the
+`content-length` check exists; raising the default because "10 MB is small" —
+raise it per-route via `maxBodySize` instead; reading the body with a plain
+`request.arrayBuffer()` anywhere that bypasses this method; and adding an
+adapter that buffers a body without a bound, on the assumption that some layer
+downstream will catch it.