@pikku/core 0.12.142 → 0.12.144

package/knowledge/decisions/security/analytics-identity-is-stamped-from-the-session-not-the-event.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Analytics identity is stamped from the session and resolvers, never from the event body
-description: Each analytics record takes userId and orgId from the wire session, pikkuUserId from the wire, and the rest from the identity resolvers, not from the event payload
-tags: core, analytics, security
----
-
-# Analytics identity is stamped from the session and resolvers, never from the event body
-
-`resolveEvent` in `packages/core/src/analytics/analytics.ts:55-72` builds
-`userIdentity` from the wire session (`:59`, `:67-69`), `this.wire.pikkuUserId`
-(`:70`), and the output of the identity resolver (`:61`, `:71`). The event's own
-fields are `name`, `props` and the optional `at` (`:60`, `:66`). The identity
-fields are not read from the event.
-
-`packages/core/src/analytics/analytics.types.ts:26-29` gives the reason: identity
-is stamped server-side and never read from the request body, which is what makes
-an unauthenticated ingest safe to expose.
-
-The consent notes in this folder cover the cookie side of identity. They do not
-cover how the record's identity is attached.
-
-**What this rules out:** a client supplying `userId`, `orgId` or `pikkuUserId` in
-an analytics event and having it recorded as the caller's identity.

package/knowledge/decisions/security/app-access-is-a-scope-tree-synthesised-from-virtual-users.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: App access is a scope tree synthesised from the virtual users that name an app
-description: buildAppScopeDefinition creates one app:<name> scope per app any virtual user names, so which frontend a person may sign into is a runtime-revocable grant rather than a column per app
-tags: core, virtual-users, scopes, access
----
-
-# App access is a scope tree synthesised from the virtual users that name an app
-
-`packages/core/src/wirings/virtual-user/virtual-user-app-scopes.ts` builds an `app` scope
-tree from the virtual users. `declaredApps` returns the app names used by virtual users,
-sorted and without duplicates (`virtual-user-app-scopes.ts:23-30`).
-`buildAppScopeDefinition` creates one child scope per app, with the origin
-`generated` (`virtual-user-app-scopes.ts:60-74`). It returns `null` when no virtual user
-names an app (`virtual-user-app-scopes.ts:55-58`).
-
-The doc comment gives the reasons. Which frontend a person may use is the same
-kind of question as a scope: an admin can grant and revoke it at runtime, it
-resolves at the session boundary, and a restricted API key can decline to inherit
-it (`virtual-user-app-scopes.ts:35-41`). The tree is synthesised, not written by hand,
-because a hand-written copy could drift from the virtual users. The comment says that
-failure "is one `pikku scopes prune` away from silently revoking sign-in"
-(`virtual-user-app-scopes.ts:45-47`).
-
-**What this rules out:** a separate per-app access column, and a hand-maintained
-list of apps that has to match the virtual users.

package/knowledge/decisions/security/approval-policy-decides-who-answers-a-tool-call.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: The approval policy decides who answers a tool call
-description: The conversation approvals option picks either a fixed answer or the virtual user's model for each pending tool call, and a call with no answer is denied
-tags: core, virtual-users, approvals, security
----
-
-# The approval policy decides who answers a tool call
-
-`ConversationApprovalPolicy` in
-`packages/core/src/wirings/virtual-user/conversation/conversation.types.ts:1` has
-three values, and `approvals` is an optional field on `ConverseOptions` (`:9`).
-
-`decideApprovals` in
-`packages/core/src/wirings/virtual-user/conversation/run-conversation.ts:133-181`
-applies it. The default is `in-virtual-user` (`:138`). `always` approves every
-pending call and `never` denies every one (`:139-144`). `in-virtual-user` sends the
-pending calls to the virtual user's model with `tools: []` and `toolChoice: 'none'`
-(`:153-169`), and the model's decisions are what get applied.
-
-Every pending call must get a decision. The code maps the answers by `toolCallId`
-and a call with no answer is denied (`:176-180`). The missing-decision rule has
-its own note,
-[missing approval decisions default to denied](virtual-user-conversation-missing-approval-decisions-default-to-denied.md).
-
-**What this rules out:** reading a missing answer as consent, and an
-`in-virtual-user` run approving a call the virtual user's model did not name.

package/knowledge/decisions/security/auth-false-on-a-session-function-warns-and-still-requires-one.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: auth false on a session-required function warns and still requires a session
-description: Writing auth: false on a function that is not sessionless does not open it; the runner logs a warning and still throws MissingSessionError without a session
-tags: core, auth, function-runner
----
-
-# auth false on a session-required function warns and still requires a session
-
-In `runPikkuFunc` (`packages/core/src/function/function-runner.ts`), a function
-that is not `sessionless` is session-required. If the wiring or the function
-config says `auth: false`, the runner logs
-"requires a session but auth was explicitly disabled — use pikkuSessionlessFunc
-instead." and then still throws `MissingSessionError` when no session is present.
-
-The test "should warn when auth is disabled for a session-required function but
-still enforce session" in `function-runner.test.ts` states the intent. The
-warning points the author at the function kind that actually means "no session",
-which is `pikkuSessionlessFunc`. The same flag on a sessionless function is the
-opposite declaration and is covered by
-[A public function says so with auth: false](a-public-function-says-so-with-auth-false.md).
-
-**What this rules out:** treating `auth: false` on a `pikkuFunc` as making it
-public. Making a function public means using `pikkuSessionlessFunc`, and a
-session-required function that disables auth still fails closed.

package/knowledge/decisions/security/bearer-token-hashes-are-unpeppered-sha256.md

@@ -1,18 +0,0 @@
----
-type: decision
-title: Bearer token hashes are unpeppered SHA-256
-description: hashToken stores bearer tokens as plain SHA-256 hex because they are high-entropy random values; a low-entropy secret is not a hashed column
-tags: core, classification, security
----
-
-# Bearer token hashes are unpeppered SHA-256
-
-`hashToken` in `packages/core/src/classification/column-form.ts:21-32` returns the
-lowercase hex SHA-256 of its input through WebCrypto. The doc comment at `:8-15`
-gives the reason: bearer tokens are high-entropy random values with no candidate
-set to search, so a pepper would add a key to manage and a rotation story while
-buying nothing. The same comment says a column that holds a low-entropy secret is
-not a `hashed` column and needs a password KDF instead.
-
-**What this rules out:** adding a pepper or key to token hashes, and using this
-hash for passwords or other low-entropy values.

package/knowledge/decisions/security/consent-is-read-from-a-cookie-and-a-recognised-denial-counts-as-refusal.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: Consent is read from a cookie, and a recognised denial value counts as a refusal
-description: cookieAnalyticsIdentity grants a consent purpose only when its cookie is present and not one of a fixed set of denial values, and resolves no identity off a non-HTTP wire
-tags: core, analytics, consent, cookies
----
-
-# Consent is read from a cookie, and a recognised denial value counts as a refusal
-
-`packages/core/src/analytics/cookie-analytics-identity.ts` reads consent and
-vendor identifiers from first-party cookies. The doc comment says a purpose is
-true "only when the cookie is present and is not a recognised denial", so a
-consent tool that writes a refusal rather than deleting the cookie is read as a
-refusal (`cookie-analytics-identity.ts:7-11`).
-
-The denial values are `0`, `false`, `denied`, `deny` and `no`
-(`cookie-analytics-identity.ts:15`). The comparison is case-insensitive
-(`cookie-analytics-identity.ts:49`).
-
-A purpose whose cookie is absent is left out of the consent record entirely
-(`cookie-analytics-identity.ts:47-48`). Since `mintCookie` requires `=== true`
-(`mint-cookie.ts:34`), an absent cookie is a refusal there.
-
-A wire with no HTTP request resolves nothing (`cookie-analytics-identity.ts:34-35`).
-The doc comment says a cron task or queue worker has no browser, so "any vendor
-id they produced would be invented" (`cookie-analytics-identity.ts:24-25`).
-
-**What this rules out:** treating any present cookie value as consent, and
-inventing a vendor identity for a non-browser caller.

package/knowledge/decisions/security/console-addon-privileged-functions-gate-themselves.md

@@ -1,84 +0,0 @@
----
-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, 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. Every console function now declares its own
-`pikku:console:<area>:<action>` scope instead, which the function runner
-enforces per call. A blanket `wireAddon({ …, scopes: ['admin'] })` stood in for
-that briefly; it is gone, because a single grant covering secrets, source
-editing and the audit trail alike is not something an operator can reason
-about.
-
-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: ['pikku:console:addons:install']`, enforced by `verifyScopes` in the
-function runner before the body runs. Both gates are
-checked whether or not the host registered a global permission — an app that
-hand-wires `wireAddon({ name: 'console', package: '@pikku/addon-console' })`
-still cannot reach `execFileSync` unauthenticated.
-
-The scopes are spelled as literals here because they are scope ids in this
-addon's own `wireScope` tree. The `admin:scopes:*` gates on the scope-admin
-functions come from a different tree — those functions now live in
-`@pikku/addon-admin`, which declares its own. The generated secret and variable
-brokers live in the app's own scaffold rather than the addon, so the addon
-boundary never covered them; they carry `pikku:console:secrets:*` and
-`pikku:console:variables:*` themselves.
-
-**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]],
-[[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

@@ -1,39 +0,0 @@
----
-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

@@ -1,37 +0,0 @@
----
-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/cors-defaults-to-any-origin-and-refuses-the-wildcard-with-credentials.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: CORS defaults to any origin and refuses the wildcard when credentials are on
-description: The cors middleware's origin defaults to *, and a resolved wildcard origin combined with credentials throws when the middleware is built
-tags: core, middleware, cors, security
----
-
-# CORS defaults to any origin and refuses the wildcard when credentials are on
-
-In `packages/core/src/middleware/cors.ts`, `origin` defaults to `'*'` (`:29`) and
-`credentials` defaults to `false` (`:33`). The factory throws when the resolved
-origin is `'*'` and credentials are on (`:36-40`). Because the check runs on the
-resolved value, the default origin with `credentials: true` throws too.
-
-A `true` origin reflects the request's own origin, or `*` when none is sent
-(`:55-56`). An array origin answers with the request origin only when it is in the
-list (`:57-61`). Any other request origin is left out of the response, with a debug
-log (`:62-65`).
-
-**What this rules out:** a wildcard origin together with credentials.
-`questions/does-cors-origin-true-reflect-any-origin-with-credentials.md` records
-the `true` case, which this check does not refuse.

package/knowledge/decisions/security/credential-backends-share-one-conformance-suite-for-per-user-isolation.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: Credential backends are checked by one conformance suite that proves per-user isolation
-description: defineCredentialServiceTests asserts that one user's credential is invisible to another and that KEK rotation re-wraps stored values, for any backend that supplies a credential service
-tags: core, credentials, testing, isolation
----
-
-# Credential backends are checked by one conformance suite that proves per-user isolation
-
-`defineCredentialServiceTests` in `packages/core/src/testing/service-tests/credential-service-tests.ts`
-is the shared conformance suite for `credentialService`. Its doc comment says it
-"runs only when a backend supplies one" (`credential-service-tests.ts:6`), so a
-backend without a credential service is not checked by it.
-
-Per-user isolation is asserted directly. A value set for `user-1` is read back
-only for `user-1`, and `user-2` gets its own value (`credential-service-tests.ts:53-62`).
-A delete for one user leaves the other user's credential in place
-(`credential-service-tests.ts:64-72`). `getAll` for one user returns that user's
-credentials and omits another user's (`credential-service-tests.ts:85-95`), and
-returns `{}` for an unknown user (`credential-service-tests.ts:97-101`).
-
-KEK rotation is asserted too. After rotation to a new key version, a credential
-written under the old key is still readable, and the new key alone can read it
-(`credential-service-tests.ts:103-133`). Rotation without a `previousKey` throws
-(`credential-service-tests.ts:135-141`).
-
-**What this rules out:** a credential backend that returns one user's stored value
-to another user, or that rotates keys without re-wrapping existing credentials,
-while still passing the suite.

package/knowledge/decisions/security/each-stage-has-one-virtual-user-key-pair.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: Each stage has one virtual user key pair, and the app holds only the public half
-description: The deployer holds the private key, the app reads the public key from an unreserved variable, and users never see either
-tags: services
----
-
-# Each stage has one virtual user key pair, and the app holds only the public half
-
-| Environment | Private key held by | Public key reaches the app as |
-| --- | --- | --- |
-| `pikku dev` | Generated on first start into `<runtimeDir>/virtual-user/signing.key` (mode 0600, a `.gitignore` of `*` beside it); the CLI reads it there | `process.env.VIRTUAL_USER_VERIFY_KEY`, set before services are built |
-| Pikku Studio Cloud stage | Pikku Studio Cloud's backend, one pair per stage | the stage variable `VIRTUAL_USER_VERIFY_KEY`, set by Pikku Studio Cloud |
-| Open source deploy | The deployer's machine, as `VIRTUAL_USER_SIGNING_KEY` in the environment of whoever runs the CLI | the variable `VIRTUAL_USER_VERIFY_KEY`, set by the deployer |
-
-The app reads it with `variables.get('VIRTUAL_USER_VERIFY_KEY')`: the SPKI DER, base64
-on one line (a PEM is also accepted). A stage without it registers no statement
-endpoint, and the CLI's error for that says which variable to set.
-
-**One pair per stage** so a statement for one stage verifies nowhere else; the
-audience check is a second line, not the first. **Unreserved names**: neither starts
-with `PIKKU_` or `PIKKUSTUDIO_`, which a platform may refuse to let an app or a deployer
-set. **Users never manage keys**: `pikku dev` makes them and a deploy supplies them.
-
-**What this rules out:** one key shared across stages, a private key stored in the
-app's variables or secrets, and a key a person has to generate or paste to run
-scenarios locally.

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

@@ -1,41 +0,0 @@
----
-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 synthetic registration **inherits the wired function's own metadata** —
-`sessionless`, input and output schema names, `scopes`, tag middleware — read
-back from `pikkuState(null, 'gateway', 'meta')[name].pikkuFuncId`, which the
-inspector already records. The synthetic id exists so the gate runs; it is not a
-licence to run the handler under metadata its author never wrote. A handler
-declared with `pikkuFunc` says session-required in meta rather than through an
-`auth` property, and that declaration is honoured.
-
-When nothing was declared — no inspector entry, as when a gateway is wired by
-hand — the handler falls back to `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 fabricating the handler's metadata rather
-than inheriting it, and flipping the _fallback_ to session-required as a
-hardening measure — that breaks every webhook that declared nothing, 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

@@ -1,30 +0,0 @@
----
-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

@@ -1,40 +0,0 @@
----
-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/hmac-verification-fails-closed-on-empty-inputs.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: HMAC verification fails closed on empty or malformed inputs
-description: verifyHmacSignature returns false for an empty secret, a missing signature, an unknown algorithm, an empty key, a malformed hex signature or an empty signature
-tags: core, security, webhooks
----
-
-# HMAC verification fails closed on empty or malformed inputs
-
-`verifyHmacSignature` in `packages/core/src/utils/hmac.ts:142-161` returns `false`
-in each of these cases:
-
-- an empty secret or a missing signature (`:150`);
-- an algorithm with no entry in `HMAC_HASH` (`:153`);
-- a secret that decodes to an empty key (`:155`);
-- a hex encoding whose signature does not match `^(?:[0-9a-fA-F]{2})+$` (`:156-158`);
-- a signature that decodes to zero bytes (`:161`).
-
-The key is imported with WebCrypto `importKey` (`:162-166`). The doc comment at
-`:139-140` says the comparison is `crypto.subtle.verify('HMAC', ...)`, which runs
-in the platform's constant-time implementation. `timingSafeStringEqual`
-(`:52-63`) is a separate helper for opaque tokens and is not used for HMACs.
-
-**What this rules out:** treating an empty secret, or a signature that does not
-decode, as a match.

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

@@ -1,33 +0,0 @@
----
-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

@@ -1,46 +0,0 @@
----
-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.