@pikku/core 0.12.72 → 0.12.77

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]].

package/knowledge/decisions/security/queue-jobs-carry-the-producers-pikku-user-id.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: Queue jobs carry the producer's pikku user id
+description: A job's pikkuUserId is trusted as identity by the worker, so enqueue rights are effectively act-as-user rights
+tags: queue
+---
+
+# Queue jobs carry the producer's pikku user id
+
+`JobOptions.pikkuUserId` (`packages/core/src/wirings/queue/queue.types.ts`) is
+set by whoever enqueues the job. The adapter surfaces it as
+`QueueJob.pikkuUserId`, `runQueueJob` in
+`packages/core/src/wirings/queue/queue-runner.ts` copies it onto the wire as
+`PikkuQueue.pikkuUserId`, and `resolveSession` in
+`packages/core/src/function/function-runner.ts` then resolves it through
+`defaultPikkuUserIdResolver` and loads that user's session out of the
+`sessionStore`. The worker function runs with that session.
+
+The claim is now HMAC-signed at enqueue and verified in `runQueueJob` — see
+[[queue-job-identities-are-signed-at-enqueue]], which supersedes the "any
+producer may name any user" reading below. Everything here still holds for the
+*authorization* question: signing proves the producer held the deployment
+secret, not that it was entitled to name that user.
+
+There is no re-authentication at the worker boundary — the queue payload *is* the
+credential. Workers run with `auth: false`, so nothing downstream re-checks that
+the producer was entitled to name that user. This is deliberate: the whole point
+is to let a background job resolve the same per-user credentials the original
+request had, without persisting a token in the queue. The cost is that write
+access to the queue is equivalent to being able to act as any user whose session
+is in the store.
+
+**What this rules out:** exposing job enqueue to untrusted callers, or letting a
+client-supplied field flow into `JobOptions.pikkuUserId` without an authorization
+check first. It also rules out treating the queue as an authorization boundary —
+do not add a "the worker validated the producer's rights" assumption anywhere
+downstream, and do not drop the id from the wire on the theory that workers are
+unauthenticated anyway. Dropping an id that fails *signature* verification is a
+different matter and is what the worker now does.

package/knowledge/decisions/security/remote-addon-tokens-are-client-credentials-not-mesh-trust.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: Remote addon tokens are client credentials, not mesh trust
+description: wireRemoteAddon authenticates as a client to a hosted library and fails closed on an empty token; it never uses PIKKU_REMOTE_SECRET
+tags: rpc
+---
+
+# Remote addon tokens are client credentials, not mesh trust
+
+`resolveRemoteAddonToken` in
+`packages/core/src/wirings/rpc/remote-addon-auth.ts` resolves the bearer token a
+`wireRemoteAddon` consumer sends to the host. This is a **client** authenticating
+to a hosted library — it is not pikku's trusted machine-to-machine mesh, which
+uses `PIKKU_REMOTE_SECRET`. Conflating the two would hand a third-party addon
+host a credential that grants mesh-level trust inside the consumer's own
+deployment.
+
+The consumer binds the addon's declared auth requirement to one of three local
+sources: `credentialId`, a per-user credential read through `wire.getCredential`
+and therefore scoped to `pikkuUserId`; `secretId`, a platform key from the
+secrets service; or `resolve`, a custom escape hatch. The resolved token is never
+logged or traced. Binding a `credentialId` without a wire that supports
+credentials throws rather than falling back to a shared secret.
+
+Resolution fails closed. `null` is returned only when no auth is bound at all,
+which is the addon declaring its remote surface public. Once auth *is* bound, a
+resolved value of `null`, `undefined` or `''` raises `RemoteAddonAuthError` (401)
+instead of dispatching an unauthenticated request that the host might accept as
+anonymous.
+
+**What this rules out:** defaulting to `PIKKU_REMOTE_SECRET` or any ambient
+credential when the bound source comes up empty, treating an empty token as
+"public", and adding the token to log lines, trace headers or error messages for
+debugging.

package/knowledge/decisions/security/scaffold-features-are-authenticated-unless-opted-out.md

@@ -0,0 +1,49 @@
+---
+type: decision
+title: A scaffolded surface is authenticated unless the config opts out in writing
+description: 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
+tags: config, authorization, codegen, scaffold
+---
+
+# A scaffolded surface is authenticated unless the config opts out in writing
+
+`scaffold.<feature>` was `'auth' | 'no-auth' | false`. Two things were wrong
+with it, and they compounded.
+
+The auth dimension asked the wrong question of some features and the right one
+of others. For `rpc` it is a blanket "no anonymous RPC in this app", set on a
+dispatcher that cannot know what it dispatches to — wrong the moment one
+legitimately public sessionless function exists. For `userAdmin` it was
+redundant: the generated functions are `pikkuFunc` with `scopes:
+['admin:users:list']`, gated twice over already. But for `agent`, `workflow`,
+`events` and `scenarios` it was the *only* gate, because those generate real
+endpoints the app never authors and has nowhere else to declare a gate for.
+A uniform collapse to boolean would have silently opened four surfaces.
+
+And the value read like a preference. `"rpc": "no-auth"` looks like a
+starter-file setting; it was a live authorization decision, three directories
+from the functions it governed. That is the shape the console incident took.
+
+The type is now `boolean | { auth?: boolean; path?: string }`. `true` means
+enabled **and authenticated**; a surface becomes public only by writing
+`{ auth: false }`. Omitting a field can then never open anything — the failure
+mode of a forgotten flag is a locked door. Features with no auth dimension
+(`webhook`, `remoteRpc`, whose generator hardcodes `auth: false`) simply ignore
+it.
+
+The object form is also what makes the legacy strings safe to remove. An
+earlier design used `string` for the output path, under which `"no-auth"` would
+have parsed as *a file named `no-auth`* — every unmigrated config silently
+producing nonsense instead of failing. With `boolean | object`, a string is
+never valid, so `resolveScaffoldFeature` refuses `'auth'` and `'no-auth'` by
+name and prints the replacement. Coercing them was rejected outright: the value
+it would coerce to is the one that caused the incident.
+
+Reading happens once, in `pikku-cli-config.ts`, so a legacy value fails at load
+with the migration named rather than downstream where it has already become
+something plausible.
+
+**What this rules out:** a bare `true` that means "public"; inferring a
+feature's auth posture from its default; using `string` for the output path
+while the legacy string values still exist in the wild; and collapsing the auth
+dimension uniformly across features that do not all have one.

package/knowledge/decisions/security/scenario-step-functions-are-never-externally-invocable.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: Scenario-step functions are never externally invocable over RPC
+description: rpcExposed requires expose and rejects scenarioStep, so test steps stay reachable only from inside a scenario run
+tags: rpc
+---
+
+# Scenario-step functions are never externally invocable over RPC
+
+`ContextAwareRPCService.rpcExposed` in
+`packages/core/src/wirings/rpc/rpc-runner.ts` is the entry point for RPCs that
+arrive from outside the process. It resolves the function's meta and throws
+`RPCNotFoundError` unless `functionMeta.expose` is set **and**
+`functionMeta.scenarioStep` is falsy — the same 404 an unknown name gets, so the
+existence of a hidden function is not disclosed.
+
+A scenario step is a piece of a test scenario: it may drive a browser, assert
+against fixtures, or reach for privileged setup helpers. Steps are dispatched by
+name from inside a scenario run through the internal `rpc` path, which does not
+consult `expose`. If a step were also reachable from the outside, any caller who
+guessed its name would get an unauthenticated handle on test tooling in whatever
+environment the scenario code shipped to.
+
+The two conditions are independent and both required: `expose` opts a function
+into the external surface, `scenarioStep` opts it back out regardless.
+
+**What this rules out:** collapsing the check to `!functionMeta.expose`,
+returning a distinct "forbidden" error that confirms the name exists, and routing
+external traffic through `rpc` instead of `rpcExposed` for convenience — `rpc`
+performs no exposure check at all.

package/knowledge/decisions/security/scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: Scope resolution happens at the session boundary and scope sync never deletes
+description: ScopeService is called when a session is built, never by the function runner, and syncScopes only ever adds — revoking is an explicit operation
+tags: services
+---
+
+# Scope resolution happens at the session boundary and scope sync never deletes
+
+Implementations of `ScopeService` (`packages/core/src/services/scope-service.ts`)
+are called at the session boundary — better-auth's `mapSession`, for instance —
+and never by the function runner. The runner reads `session.scopes` and performs
+no I/O of its own, which is what keeps it viable on Workers and Lambda. Because
+the session is rebuilt per request, a scope change takes effect on the next call:
+nothing is cached and there is nothing to invalidate.
+
+`syncScopes` is additive and never deletes. Scopes are declared in code, so a
+declaration removed in a deploy would otherwise revoke a live grant the moment
+the new build boots — silently, mid-rollout, for everyone holding it. Instead the
+row stays and goes inert: `listScopes` reports it as `declared: false`, no
+function can require it, `findStaleScopes` surfaces it for `pikku scopes audit`,
+and `pikku scopes prune` is the explicit act that removes it.
+
+**What this rules out:** having the function runner resolve scopes per call (it
+would put a store round-trip in every request path and break the Workers/Lambda
+story), caching resolved scopes anywhere, and making `syncScopes` reconcile —
+diffing declared against stored and deleting the difference. A deploy must never
+be able to revoke a grant as a side effect.

package/knowledge/decisions/security/self-authentication-is-declared-not-detected.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: Self-authentication is declared, not detected
+description: A function that authorizes callers in its own body says so with selfAuthenticated; codegen never tries to infer it
+tags: permissions, codegen
+---
+
+# Self-authentication is declared, not detected
+
+Some functions are genuinely closed while carrying no session, scope or
+permission: a webhook receiver that verifies a signature, a handler that
+redeems a signed invite, an exchange endpoint that validates a token before it
+does anything. Nothing in meta distinguishes those from a function nobody
+remembered to gate, so `validateExposedFunctionsGated` (PKU574) would warn about
+them on every build.
+
+The fix is a declaration — `selfAuthenticated: true` on the function config —
+not analysis of the body. Detection would have to recognise an open-ended set of
+authorization idioms, and it fails in the expensive direction: a body that
+*looks* like it checks something silences the warning for a function that
+checks nothing. A declaration cannot be wrong by accident. Someone typed it,
+it is greppable, and it survives into meta where an audit reads it as what it
+is — a claim by a named author, not an inference.
+
+It carries no runtime effect and grants nothing. Its entire job is to move a
+gate that codegen cannot see into a place where a human can, and to keep PKU574
+worth reading: a warning that is usually wrong stops being read, which costs
+more than the warning ever saved.
+
+**What this rules out:** inferring self-authentication from the function body or
+from what it imports; giving `selfAuthenticated` any runtime meaning (it must
+never be a way to skip a check the runtime would otherwise run); and dropping
+the PKU574 warning instead, which was the alternative that would have left every
+genuinely ungated function silent too.

package/knowledge/decisions/security/signed-content-urls-bind-the-request-path.md

@@ -0,0 +1,37 @@
+---
+type: decision
+title: Signed content URLs bind the request path and verify fail-closed
+description: A signature that only carries timestamps authorizes every asset, and a verifier with no key must refuse rather than allow
+tags: content
+---
+
+# Signed content URLs bind the request path and verify fail-closed
+
+`LocalContent` signs a payload containing the decoded request path, and the
+verifier in `pikku-node-http-server.ts` compares it against the path actually
+requested. `LocalContent` requires a `JWTService` and throws without one; a
+verifier with no key available rejects with 403 rather than allowing the
+request, logging once per process so an attacker-triggerable path cannot flood.
+
+A signature over `{signedAt, expiresAt, notBefore}` alone proves only *when* a
+URL was issued, never *what* it was issued for. Any valid token was a skeleton
+key: swap the pathname from a public thumbnail to a private document and the
+signature still verifies. Timestamps bound the window; only the path binds the
+asset.
+
+The path is the representation both signing entry points can produce and the
+verifier can reconstruct — it sees a request line, and cannot recover the
+bucket/key split from it. `signedContentPath` normalizes both sides identically
+(pathname only, origin and query dropped, `decodeURIComponent` falling back to
+the raw pathname on a malformed escape) so a difference in encoding cannot
+become a difference in verdict.
+
+`pikku serve` and `pikku dev` mint an ephemeral per-process signing key, so
+local content serving works with no configuration without shipping a fail-open
+path. URLs signed by one dev-server process are meaningless to the next, which
+is the correct lifetime for a dev secret.
+
+**What this rules out:** signing a URL without binding it to what it grants;
+returning "valid" from a verifier that could not check anything; normalizing the
+path differently on the two sides; and constructing `LocalContent` without a
+JWT service.

package/knowledge/decisions/security/webhook-bodies-are-signed-before-they-are-enqueued.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Webhook bodies are signed before they are enqueued
+description: QueueWebhookService computes the HMAC at enqueue time so the signing key never travels in the queue payload
+tags: services
+---
+
+# Webhook bodies are signed before they are enqueued
+
+`QueueWebhookService.prepareDelivery`
+(`packages/core/src/services/queue-webhook-service.ts`) serialises the payload,
+resolves the signing secret, computes the signature and writes it into the job's
+`headers` — all before `queueService.add` is called. The worker,
+`pikkuWebhookWorkerFunc`, POSTs headers it was handed and never sees a secret.
+
+Signing in the worker instead would mean the key has to reach the worker, and the
+only channel between the two is the queue payload: an SQS body, a Redis value, a
+`jsonb` column, all of which are at rest, replicated, and visible to anyone who
+can read the queue. The signature is not sensitive; the key is.
+
+**What this rules out:** moving signing into the worker so it can re-sign on
+retry, and putting `secret` (or a resolved key of any kind) onto `WebhookJobData`.
+Note the related consequence: because the signature is fixed at enqueue time, a
+key rotated between enqueue and delivery does not change an in-flight job's
+signature — that is intended, not a bug to fix by carrying the key.

package/knowledge/decisions/security/workflow-actor-steps-always-use-the-real-transport.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: A scenario actor step always goes over the real transport and never through internal dispatch
+description: Internal dispatch would bypass auth middleware and permissions, turning a scenario into a green health check that proves nothing
+tags: workflow
+---
+
+# A scenario actor step always goes over the real transport and never through internal dispatch
+
+When a workflow step carries `options.actor`, `rpcStep` in
+`pikku-workflow-service.ts` calls `actor.invoke(rpcName, data)` — the actor's
+authenticated client, over the real network transport — and never falls back to
+internal dispatch. Internal dispatch skips auth middleware and permission
+checks, so a scenario that "passed" that way would prove only that the function
+body runs, not that the persona is allowed to run it. That is a green health
+check for a system that may be wide open.
+
+For the same reason, actor steps never queue: `rpcStep` short-circuits
+`dispatchStep` to `false` whenever `options.actor` is set. An actor step is an
+outbound HTTP call made by the runner itself, and the actor's session lives in
+this process — a queued worker in another process would have no session to make
+it with. The step is still recorded durably like any RPC step, so replay and
+reporting are unaffected.
+
+Actor identity is process-local by nature. `PikkuScenarioService.runActors` maps
+run id to live authenticated clients (cookie jars), and those ride that map
+only, never the persisted run wire — a serialized session on a durable run row
+would be a credential at rest.
+
+**What this rules out:** adding an "internal dispatch is faster" fast path for
+actor steps, routing an actor step through the queue, serializing actor sessions
+onto the run wire, or letting `actor.invoke` degrade to `rpcWithWire` when the
+transport is unavailable. Each turns an end-to-end authorization test into one
+that cannot fail.

package/knowledge/decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: An approval decision is stored raw and validated on replay, and an invalid one closes the gate rather than failing the run
+description: The schema only exists inside the workflow body, and letting an external payload fail the run would let any caller kill a workflow
+tags: workflow
+---
+
+# An approval decision is stored raw and validated on replay, and an invalid one closes the gate rather than failing the run
+
+`approveStep` in `pikku-workflow-service.ts` is called from outside the workflow
+— an HTTP route, an RPC — where the approval's schema value is not in scope. It
+therefore stores the decision payload raw in run state and does nothing else.
+Validation happens on replay inside `approvalStep`, in the workflow body, which
+is the only place the schema exists.
+
+When validation fails, the bad decision is dropped, the issues are recorded on
+the gate's state record, and a `WorkflowSuspendedException` re-closes the gate.
+The failure stays legible to whoever tries next, and — the security point —
+failing the run instead would let any caller kill a workflow with a malformed
+payload. A later valid decision still lands normally.
+
+`WorkflowApprovalOptions.schema` is a VALUE, not a type generic, for the same
+reason: the payload arrives from an untrusted caller over the approve wire, and
+a generic is erased at compile time, so it would validate nothing. Any
+standard-schema library (zod, valibot, arktype) satisfies it. The contract is
+the `~standard` spec and nothing more: `@pikku/core` deliberately carries no
+zod dependency, which is why `pikku-workflow-service.test.ts` hand-rolls a
+minimal `StandardSchemaV1` rather than importing a validation library.
+
+A decision arriving for a gate that has already resolved is rejected with
+`WorkflowApprovalResolvedError` (409) rather than accepted and dropped. The gate
+caches its outcome as the step result and never re-reads run state, so a
+decision recorded after resolution could not take effect — most obviously when
+it loses the race with expiry — and the approver has to be told their decision
+did not land.
+
+**What this rules out:** validating in `approveStep` (the schema is not there),
+failing the run on an invalid payload, turning `schema` into a type parameter,
+accepting a decision on a resolved gate, or making a resolved gate re-read run
+state so a late decision "wins".