@pikku/core 0.12.71 → 0.12.74

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.

package/knowledge/decisions/security/index.md

@@ -0,0 +1,55 @@
+---
+type: overview
+title: Security decisions
+description: Who may do what in core — gates, defaults, and the failures they are chosen to cause
+---
+
+# Security decisions
+
+A rule about who may do what, and which way it fails when it is unsure.
+
+<!-- pikku:knowledge-index -->
+- [A dropped audit write is always logged](a-dropped-audit-write-is-always-logged.md) — The no-op audit service falls back to the singleton logger when the wire carries none, so an unconfigured audit call is never silent
+- [An actor's missing approval decision defaults to denied](actor-flow-missing-approval-decisions-default-to-denied.md) — Every pending tool call gets an explicit decision; an id the persona LLM omitted is denied, so a dropped field can never read as consent
+- [Actor sign-in is proven by Set-Cookie, not a non-empty jar](actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md) — HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
+- [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
+- [Addon auth and tags only tighten, and resolve where the function runs](addon-auth-and-tags-only-tighten.md) — 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
+- [Addon auth and tag gates apply wherever the function runs, including inside the addon](addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md) — 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
+- [Addon scopes are resolved where the function runs](addon-scopes-are-resolved-where-the-function-runs.md) — wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace
+- [Only a Symbol-branded framework result can request tool approval](ai-agent-approval-forwarding-requires-a-symbol-brand.md) — Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
+- [Credential requests are trusted only when Symbol-branded](ai-agent-credential-requests-are-symbol-branded.md) — The string key is a wire field; the Symbol is the capability, and only core can mint it
+- [An agent requires a session only when auth is true, but always enforces scopes and permissions](ai-agent-gate-requires-a-session-only-when-auth-is-true.md) — Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O
+- [An agent ownership failure never echoes the resource it refused](ai-agent-ownership-failures-never-echo-the-resource.md) — assertResourceOwner throws a bare ForbiddenError so the error cannot be used as an existence oracle, at the cost of thinner debugging output
+- [Resuming a suspended agent run re-runs the agent's authorization gate](ai-agent-resume-re-runs-the-authorization-gate.md) — Ownership of the run is not enough — a grant revoked while the run was suspended must block the approval
+- [Agent thread ownership fails closed when there is no principal](ai-agent-sessionless-deployments-have-no-thread-ownership.md) — A sessionless caller gets an ephemeral owner and reaches no stored thread, rather than reaching all of them
+- [An agent thread key is always prefixed with the trusted principal](ai-agent-thread-ownership-composes-the-session-principal.md) — Ownership keys are composed as principal:resourceId, so a client id can sub-divide its own boundary but never widen it
+- [Agent tool permission filtering reads the live function config, not the metadata](ai-agent-tool-filtering-reads-the-live-function-config.md) — The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
+- [An empty owners constraint matches nothing](an-empty-owners-constraint-matches-nothing.md) — owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
+- [An exposed function with no gate is reported at codegen, not at boot](an-exposed-ungated-function-is-a-codegen-warning.md) — 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
+- [The console addon's privileged functions gate themselves](console-addon-privileged-functions-gate-themselves.md) — 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
+- [Core's SSRF guard matches host literals because edge runtimes have no DNS](core-safe-fetch-blocks-ssrf-by-host-literal-not-dns.md) — safeFetch rejects internal address literals and re-validates every redirect hop; it cannot stop DNS rebinding
+- [Core secrets are encrypted with a per-secret DEK wrapped by a KEK](core-secrets-use-a-per-secret-dek-wrapped-by-a-kek.md) — Envelope encryption keeps ciphertext untouched during key rotation, at the cost of storing two blobs per secret
+- [Gateway handlers run through the function runner gate](gateway-handlers-run-through-the-function-runner-gate.md) — A gateway's handler is registered as a real pikku function and invoked via runPikkuFunc, because calling it directly skips auth, scopes and permissions
+- [Gateway middleware sessions must be bridged onto the wire](gateway-middleware-sessions-must-be-bridged-onto-the-wire.md) — 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
+- [Global permissions and function permissions are independent gates](global-permissions-and-function-permissions-are-independent-gates.md) — Globals AND together and can only narrow access; a function's own group ORs internally and is never satisfied by a global
+- [HTTP error detail is withheld from clients in production](http-error-detail-is-withheld-from-clients-in-production.md) — 5xx bodies carry only a trace id in production; exposeErrors can widen that in development but never in production
+- [HTTP request bodies are bounded before they are buffered](http-request-bodies-are-bounded-before-they-are-buffered.md) — Content-Length is rejected up front and the stream is measured as it arrives, because that header is optional and attacker-controlled
+- [MCP internal error details are double-gated on production](mcp-internal-error-details-are-double-gated-on-production.md) — exposeErrors is checked again against isProduction() at throw time so an explicit true cannot leak stack traces from a production build
+- [Passphrases are stretched, key material is expanded](passphrases-are-stretched-key-material-is-expanded.md) — PBKDF2 guards low-entropy human input; HKDF derives from high-entropy secrets, and the two are never swapped
+- [Auth filtering requires live permission functions, never their metadata](permission-auth-filtering-requires-live-permission-functions.md) — checkAuthPermissions collects pikkuAuth-branded predicates off the real config; passing metadata would let every gated tool through
+- [Pikku carries actor scopes as data and the app grants them](pikku-carries-actor-scopes-as-data-and-the-app-grants-them.md) — scopes and roles on a ScenarioActorConfig are transported, never applied — the app's own seed reads them back and performs the grant
+- [Queue job identities are signed at enqueue](queue-job-identities-are-signed-at-enqueue.md) — A job's pikkuUserId is an HMAC claim bound to the queue and payload; an unverifiable claim is dropped, never trusted
+- [Queue jobs carry the producer's pikku user id](queue-jobs-carry-the-producers-pikku-user-id.md) — A job's pikkuUserId is trusted as identity by the worker, so enqueue rights are effectively act-as-user rights
+- [Remote addon tokens are client credentials, not mesh trust](remote-addon-tokens-are-client-credentials-not-mesh-trust.md) — wireRemoteAddon authenticates as a client to a hosted library and fails closed on an empty token; it never uses PIKKU_REMOTE_SECRET
+- [A scaffolded surface is authenticated unless the config opts out in writing](scaffold-features-are-authenticated-unless-opted-out.md) — scaffold.<feature> became boolean | { auth, path }, where true means authenticated — going public requires typing { auth: false }, and the legacy 'auth' | 'no-auth' strings are refused rather than coerced
+- [Scenario-step functions are never externally invocable over RPC](scenario-step-functions-are-never-externally-invocable.md) — rpcExposed requires expose and rejects scenarioStep, so test steps stay reachable only from inside a scenario run
+- [Scope resolution happens at the session boundary and scope sync never deletes](scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md) — ScopeService is called when a session is built, never by the function runner, and syncScopes only ever adds — revoking is an explicit operation
+- [Self-authentication is declared, not detected](self-authentication-is-declared-not-detected.md) — A function that authorizes callers in its own body says so with selfAuthenticated; codegen never tries to infer it
+- [Signed content URLs bind the request path and verify fail-closed](signed-content-urls-bind-the-request-path.md) — A signature that only carries timestamps authorizes every asset, and a verifier with no key must refuse rather than allow
+- [Webhook bodies are signed before they are enqueued](webhook-bodies-are-signed-before-they-are-enqueued.md) — QueueWebhookService computes the HMAC at enqueue time so the signing key never travels in the queue payload
+- [A scenario actor step always goes over the real transport and never through internal dispatch](workflow-actor-steps-always-use-the-real-transport.md) — Internal dispatch would bypass auth middleware and permissions, turning a scenario into a green health check that proves nothing
+- [An approval decision is stored raw and validated on replay, and an invalid one closes the gate rather than failing the run](workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md) — The schema only exists inside the workflow body, and letting an external payload fail the run would let any caller kill a workflow
+- [A queued workflow step rehydrates its session from the persisted run wire](workflow-queued-steps-rehydrate-their-session-from-the-run-wire.md) — The queue job payload is just `{ runId }`, so without threading `pikkuUserId` an authed step sees no session and throws
+- [Scenario sessions are isolated per actor and reset between scenarios](workflow-scenario-sessions-are-isolated-per-actor-and-per-scenario.md) — One jar per actor keeps two personas from sharing a session; a browser reset keeps one scenario from leaving the next signed in as somebody else
+- [A scenario step is never registered as a callable RPC and never dispatched on the queue](workflow-scenario-steps-are-never-network-invocable.md) — A step drives a browser and holds an actor's session, so exposing it as an RPC would put that reach on the network
+<!-- /pikku:knowledge-index -->

package/knowledge/decisions/security/mcp-internal-error-details-are-double-gated-on-production.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: MCP internal error details are double-gated on production
+description: exposeErrors is checked again against isProduction() at throw time so an explicit true cannot leak stack traces from a production build
+tags: mcp
+---
+
+# MCP internal error details are double-gated on production
+
+`RunMCPEndpointParams.exposeErrors` in
+`packages/core/src/wirings/mcp/mcp-runner.ts` defaults to `!isProduction()`, and
+`runMCPPikkuFunc` checks `exposeErrors && !isProduction()` *again* when building
+the `-32603` internal-error response that carries `{ message, stack }`. The
+second check looks redundant against the default — it is not. The default only
+applies when the caller omits the option; a caller that passes
+`exposeErrors: true` explicitly would otherwise put the raw exception message and
+stack trace into a JSON-RPC response served from production.
+
+Internal errors reaching that branch are by definition unmapped — no `mcpCode` —
+so their message is whatever the underlying failure produced: a database error, a
+file path, a credential in a connection string. MCP responses go to a model
+client, so anything in `data` is exfiltrated into a transcript.
+
+**What this rules out:** collapsing `exposeErrors && !isProduction()` to
+`exposeErrors` on the grounds that the default already handles production, and
+adding any other MCP error path that serializes `e.message` or `e.stack` without
+its own `isProduction()` guard.

package/knowledge/decisions/security/passphrases-are-stretched-key-material-is-expanded.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: Passphrases are stretched, key material is expanded
+description: PBKDF2 guards low-entropy human input; HKDF derives from high-entropy secrets, and the two are never swapped
+tags: crypto
+---
+
+# Passphrases are stretched, key material is expanded
+
+`packages/core/src/crypto-utils.ts` carries two derivation paths that look
+alike and are not interchangeable.
+
+`encryptJSON` / `decryptJSON` take a **passphrase** and run PBKDF2-HMAC-SHA256
+at 600,000 iterations over a per-message random salt. They protect data at rest
+— the secret and credential services — where the KEK may be something a human
+chose, so the work factor is the only thing standing between a leaked ciphertext
+and a dictionary.
+
+`encryptWithKeyMaterial` / `decryptWithKeyMaterial` take **high-entropy key
+material** and use HKDF-SHA256, which is effectively free. They protect the
+remote-RPC session envelope, whose secret is a generated deployment value. HKDF
+offers no brute-force resistance at all, which is why the minimum length is
+enforced fail-closed at both ends: the entropy has to live in the secret,
+because nothing else supplies it.
+
+The split exists because the cost profiles are opposites. Stretching on a
+per-request path cost ~269ms per remote hop and would have consumed most of a
+Cloudflare Workers CPU budget; expanding a human passphrase would leave it
+one cheap hash from being guessed. Both blobs use the same
+`[salt:16][iv:12][ct+tag]` layout, so they are indistinguishable on the wire but
+cryptographically disjoint — feeding one to the other's verifier rejects.
+
+The `info` parameter namespaces each use of the same key material, so a key
+derived for one purpose cannot decrypt another's payload.
+
+**What this rules out:** using `encryptJSON` on any per-request path; using the
+key-material functions for anything a human types; sharing one derived key
+across two purposes by passing the same `info`; and lowering the minimum length
+to accommodate an existing short secret. See
+[[the-kek-salt-is-scoped-to-the-key-version]].

package/knowledge/decisions/security/permission-auth-filtering-requires-live-permission-functions.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: Auth filtering requires live permission functions, never their metadata
+description: checkAuthPermissions collects pikkuAuth-branded predicates off the real config; passing metadata would let every gated tool through
+tags: permissions
+---
+
+# Auth filtering requires live permission functions, never their metadata
+
+`checkAuthPermissions` in `packages/core/src/permissions.ts` answers "may this
+session see this function/agent at all", for listing and tool-filtering. It
+collects only predicates branded `__pikkuAuth` — from the globals and from the
+supplied group — and ignores data-dependent permissions, which cannot be
+evaluated without request data at filter time. If no auth predicates exist at
+all, the answer is `true`: nothing is gating visibility.
+
+`funcPermissions` must therefore be the **live** `CorePermissionGroup` taken from
+the function or agent config, not the metadata form. The `__pikkuAuth` brand only
+survives on the actual predicate objects, and the by-name registry that metadata
+entries would resolve against is never populated. Passing metadata compiles
+cleanly, collects nothing, hits the `authPerms.length === 0` branch and returns
+`true` — every gated tool becomes visible to every session, silently and with no
+error anywhere.
+
+Note also that the collected predicates are ORed: any one passing auth predicate
+grants visibility. This is a visibility filter only; `runPermissions` still runs
+the full gate on invocation.
+
+**What this rules out:** feeding this function anything derived from function
+metadata or a serialized permission description, and treating a `true` result as
+authorization to invoke rather than permission to list.

package/knowledge/decisions/security/pikku-carries-actor-scopes-as-data-and-the-app-grants-them.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Pikku carries actor scopes as data and the app grants them
+description: scopes and roles on a ScenarioActorConfig are transported, never applied — the app's own seed reads them back and performs the grant
+tags: services
+---
+
+# Pikku carries actor scopes as data and the app grants them
+
+`ScenarioActorConfig.scopes` and `.roles`
+(`packages/core/src/services/scenario-actors-service.ts`) come from
+`pikku.config.json` and are carried through to `scenarioActorConfigs`. Nothing in
+core reads them to grant anything. The app's seed reads them back off that config
+and performs the grants itself.
+
+Core cannot do the granting: which scope store exists, whether roles have been
+created, and what a role means are all the application's own. Worse, a framework
+that granted scopes would be a framework that can escalate an actor's privileges
+from a config file — the one place where a scenario author would least expect a
+security decision to take effect. Keeping the fields inert makes the grant an act
+the app performs deliberately, in code it owns, against a store it wired.
+
+**What this rules out:** teaching `createHttpScenarioActors` (or any core service)
+to call `ScopeService.addScopeToUser` / `addUserToRole` from these fields, and
+treating a scope listed on an actor config as evidence that the actor holds it.
+If a scenario fails on a missing scope, the fix is in the app's seed, not here.

package/knowledge/decisions/security/queue-job-identities-are-signed-at-enqueue.md

@@ -0,0 +1,69 @@
+---
+type: decision
+title: Queue job identities are signed at enqueue
+description: A job's pikkuUserId is an HMAC claim bound to the queue and payload; an unverifiable claim is dropped, never trusted
+tags: queue, crypto, security
+---
+
+# Queue job identities are signed at enqueue
+
+`QueueJob.pikkuUserId` used to be a bare string that `runQueueJob`
+(`packages/core/src/wirings/queue/queue-runner.ts`) copied onto the wire, where
+`defaultPikkuUserIdResolver` resolved it and `resolveSession` loaded that user's
+session out of the `sessionStore`. Anyone able to write to the queue backend —
+a `LPUSH` against Redis, a `SendMessage` against SQS — could name any user and
+the worker would run as them.
+
+The field now carries a signed claim instead:
+
+```
+pq1.<base64url({"u":<pikkuUserId>,"q":<queueName>,"j":<jobId>?})>.<base64url(HMAC-SHA256)>
+```
+
+The HMAC covers `pq1.<encoded claim>.<canonical JSON of the job payload>`, so a
+signature cannot be lifted onto a different queue, a different payload, or —
+when the producer knew the job id — a different job. `jobId` is optional
+because most adapters (SQS, Cloudflare Queues, Azure Storage Queues) mint the id
+after `add` returns and never see the producer's; binding the payload is what
+holds in every adapter. Canonicalization sorts keys after a JSON round trip, so
+transport reserialization cannot change the digest.
+
+The key is expanded with HKDF from `PIKKU_QUEUE_IDENTITY_SECRET`, read through
+the `SecretService`, under the `pikku:queue-identity` info namespace — the same
+deployment secret therefore cannot produce a key that opens the remote-RPC
+envelope. `signWithKeyMaterial` / `verifyWithKeyMaterial` in
+`packages/core/src/crypto-utils.ts` are WebCrypto-only because that file is in
+the Cloudflare Workers build; the `node:crypto` helpers behind
+`WebhookService.sign` are not reachable from it.
+
+Verification lives in `runQueueJob`, the single funnel every adapter calls.
+`SignedQueueService` wraps any `QueueService` to sign on the way out.
+
+Failure directions are deliberately asymmetric:
+
+- **No secret configured**: the claim is dropped, the job still runs with no
+  `pikkuUserId`, and one warning is logged per process. Hard-failing would break
+  every deployment on upgrade, and per-job logging is an attacker-triggerable
+  flood.
+- **Secret configured, claim does not verify**: the identity is dropped and the
+  rejection is logged per job — it sits alongside the per-job logs `runQueueJob`
+  already writes, so it adds no flood an attacker did not already have.
+- **Secret too short**: signing throws `WeakKeyMaterialError` at enqueue, so the
+  misconfiguration surfaces on the producer, while the worker drops the identity
+  rather than failing the job.
+
+The threat model is a **compromised or shared queue backend**, nothing more. The
+application process must hold the signing secret in order to sign, so an
+attacker who has code execution inside the app can mint any claim it likes. This
+defends the queue as a transport, not the app as a host. It also does not stop
+replay of a byte-identical job, which is indistinguishable from the redelivery
+every queue already performs; revocation is by rotating the secret.
+
+**What this rules out:** treating `JobOptions.pikkuUserId` as trusted anywhere
+downstream of the queue; letting a client-supplied value flow into it without an
+authorization check first (signing proves the producer held the secret, not that
+the producer was entitled to name that user); adding a `node:crypto` import to
+`crypto-utils.ts`; reusing `pikku:queue-identity` as the info string for any
+other purpose; and claiming this mitigates application compromise. See
+[[queue-jobs-carry-the-producers-pikku-user-id]] and
+[[passphrases-are-stretched-key-material-is-expanded]].