@pikku/core 0.12.139 → 0.12.142

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,25 @@
+---
+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/index.md

@@ -9,63 +9,127 @@ description: Who may do what in core — gates, defaults, and the failures they
 A rule about who may do what, and which way it fails when it is unsure.
 
 <!-- pikku:knowledge-index -->
-
+- [A bearer token checked against a secret is read per request, and an unreadable secret means no session](a-bearer-token-checked-against-a-secret-reads-it-per-request.md) — The secretId form of authBearer reads the secret on every request; a missing or failing read leaves the request without a session rather than raising an error
+- [A call without a session raises MissingSessionError, and a missing scope raises MissingScopeError](a-call-without-a-session-raises-missing-session-not-forbidden.md) — The function runner separates the no-session refusal from the scope and permission refusals, so a caller can tell a missing login from a denied grant
+- [A cookie the caller sets wins over the jar's copy of the same name](a-caller-cookie-wins-over-the-jar-for-the-same-name.md) — createCookieJar sends the caller's cookie for a name and drops the jar's copy of that name, so one request never carries the same cookie twice
+- [A channel lifecycle acts as the session the socket upgrade established](a-channel-lifecycle-acts-as-the-socket-upgrade-session.md) — onConnect and onDisconnect run with the userSession captured during the socket upgrade, both in the wire they receive and as the session service passed to runPikkuFunc
+- [A channel requires a session unless it says auth: false](a-channel-requires-a-session-unless-it-says-auth-false.md) — The channel-level requirement is auth !== false, and a message handler's own auth, when it is set, decides for that message in either direction
+- [A credential's read path follows its declared type, never a missing value](a-credential-read-path-follows-its-declared-type-not-absence.md) — The credential wire service reads a wire credential only from the user's store and a singleton only from the deployment, so an absent user value never falls back to the deployment's token
+- [A credential's wire or singleton type is a literal the inspector checks at declaration](a-credential-type-is-a-literal-the-inspector-checks-at-declaration.md) — defineCredential is a no-op read by AST, so its type must be a literal 'wire' or 'singleton' and the inspector refuses any other value
 - [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
+- [A first-party tracking cookie is written only after its purposes are consented](a-first-party-cookie-is-written-only-after-its-purposes-consent.md) — mintCookie writes a new cookie only when every purpose it requires is true in the consent record, and writes nothing on a wire with no HTTP response
 - [A function never receives the secret service](a-function-never-receives-the-secret-service.md) — Every function-, permission- and auth-facing services type is bounded by SecretlessServices, so reaching for `secrets` in a function body is a type error rather than a lint
 - [A graph run starts at an entry node the graph declared](a-graph-run-starts-at-an-entry-node-the-graph-declared.md) — startNode may only name a node in meta.entryNodeIds, and no generated route offers it, because otherwise a caller picks which half of the graph to skip
 - [A permission gets a wire it cannot reply on](a-permission-gets-a-wire-it-cannot-reply-on.md) — The permission wire is typed with Out = never so a permission cannot send on the channel; that narrowing is not a subtype, so the call site asserts
+- [A public function says so with auth: false](a-public-function-says-so-with-auth-false.md) — An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
+- [A readonly session reaches only functions declared readonly](a-readonly-session-reaches-only-readonly-functions.md) — A session flagged readonly is refused by every function not declared readonly, checked straight after the session is required and before scopes
+- [A scaffold flag says a surface exists, not who may call it](a-scaffold-flag-says-a-surface-exists-not-who-may-call-it.md) — scaffold.<feature> is boolean | { path } — the auth field is gone, because the function runner already enforces each generated function's own auth, wiring, scopes and addon
+- [A scheduled virtual-user run needs no admin at run time](a-scheduled-virtual-user-run-needs-no-admin-at-run-time.md) — An admin may start a virtual-user run, but the run itself never depends on an admin being signed in or on an admin's credential
+- [A scoped credential service is limited to the names its package declared](a-scoped-credential-view-is-limited-to-declared-names.md) — ScopedCredentialService refuses any credential name outside the package's declared set, filters getAll to that set, and refuses to enumerate users
+- [A scoped secret view reads only its declared keys and never writes](a-scoped-secret-view-reads-only-declared-keys-and-never-writes.md) — ScopedSecretService checks every read against an allowed-key set and refuses all writes, unlike the credential service that stays writable
+- [A secret may only be sent to the hosts its declaration names](a-secret-is-sent-only-to-the-hosts-it-declares.md) — assertSecretAllowedForHost refuses a host outside a secret's allowedHosts, and refuses any host at all for a secret with no allowedHosts when the project requires them
+- [A scenario step can name an identity no virtual user holds, through per-call headers](a-step-can-name-an-identity-no-virtual-user-holds-through-per-call-headers.md) — ScenarioInvokeOptions.headers lets a step send an impersonation or shim header on one call, and a virtual-user run never gets that option
 - [A step runs the function the workflow dispatched it with](a-step-runs-the-function-the-workflow-dispatched-it-with.md) — StepState records the step's function name so the worker can reject a queue message naming a different one, because the step executes under the run owner's identity
+- [Stopping an agent run by its id skips the ownership check; interruptAgent is the checked path](a-stopped-run-by-id-skips-the-ownership-check.md) — signalRunInterrupt is exported and performs no authorisation, while interruptAgent asserts the run's resource owner before it signals
+- [A vault secret redacts when serialized and throws when coerced to a string](a-vault-secret-redacts-on-serialization-and-throws-on-coercion.md) — SecretValue serializes to a redacted marker so logs stay honest without crashing, but string coercion throws, and reveal() is the only way to read the value
+- [Virtual users are offered calls by declared scope, and approval-gated calls are denied by default](a-virtual-user-catalogue-entry-is-filtered-by-scope-and-approval-is-denied-by-default.md) — The catalogue type filters by the declared scopes of each RPC rather than by permission functions, and the catalogue filter drops approval-required entries unless the caller opts in
+- [A virtual user's sign-in is refused unless the environment is known and allowed](a-virtual-user-environment-fails-closed.md) — Virtual user provisioning, sync and sign-in refuse when PIKKU_ENV is unresolved, unknown, production without the accountable disposition, or outside the virtual user's environments, and production environments are omitted by default
 - [A virtual user is never offered a scenario, platform or addon step](a-virtual-user-is-never-offered-a-step-that-would-forge-its-own-oracle.md) — Being able to invoke "the webhook arrives" lets the user manufacture the outcome it exists to discover, which invalidates every finding downstream
-- [A workflow run is read and approved by its owner](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it or answer its approval gates; a run with no recorded owner has no ownership to enforce
-- [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) — An actor credential mints sessions for user rows flagged actor and nothing else, so holding one never impersonates a real user
-- [An actor credential is derived per persona](an-actor-credential-is-derived-per-persona.md) — What a caller presents to the actor endpoint is HKDF-derived from the root secret and the address it signs in as, so one credential opens one persona
+- [A virtual user never runs against production, whatever its disposition](a-virtual-user-never-runs-against-production.md) — startVirtualUserRun and an enabling writeVirtualUserSchedule both refuse with a 403 in production, including for the accountable disposition; an unresolved environment counts as production
+- [A virtual user reads its roles from the app's own RPC before better-auth's user.role](a-virtual-user-reads-its-roles-from-the-apps-own-rpc-before-better-auth.md) — sessionRoles asks getMyScopes first, then get-session, and returns null rather than an empty list when the stage reports no roles
+- [A virtual-user run treats an unresolved PIKKU_ENV as production](a-virtual-user-run-treats-an-unresolved-environment-as-production.md) — The virtual-user scaffold decides "production" from the configured PIKKU_ENV environment, counts an unresolved one as production, and falls back to NODE_ENV only when no environments are configured
+- [A virtual user's scopes are expanded from its roles once, at run preparation](a-virtual-user-scopes-are-expanded-from-its-roles-once-at-run-preparation.md) — A virtual user's scope set is computed from its declared roles against the defineSystemRole definitions when the run is prepared, and that set is the oracle for scope drift
+- [A virtual user whose granted roles drift from its declaration refuses to run](a-virtual-user-whose-roles-drift-from-the-declaration-refuses-to-run.md) — verifyVirtualUserRoles compares declared and granted roles in both directions before a run, and roleMismatchMessage produces the refusal text; a provider login is never runnable
+- [A workflow run is read by its owner, and answered by whoever its gate declares](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it; who may answer an approval gate is the gate's own declaration, and a run with no recorded owner has no ownership to enforce
 - [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
-- [wireAddon expose selects the RPC surface, and a list may widen it](wire-addon-expose-selects-the-rpc-surface.md) — The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
-- [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
+- [Addon screen scopes hide a screen and do not enforce access](addon-screen-scopes-hide-and-do-not-enforce.md) — The scopes on a defineScreens entry state what a viewer must hold to see the screen; the addon's own functions are the access check
+- [Only a Symbol-branded framework result can request tool approval](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](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](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](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](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](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](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](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 addon header can only narrow the session, and an unknown addon is refused](an-addon-header-can-only-narrow-the-session.md) — addon-scope-cap intersects the session's scopes with the named addon's role, so naming an addon never widens access, and a name the host does not know is a 403
+- [An addon instance reads only the secrets and credentials it is named](an-addon-instance-reads-only-the-secrets-and-credentials-it-is-named.md) — An addon's secret and credential views are its declared names plus the consuming app's grants and override keys; the global flags opt out of scoping
+- [An addon may reach only itself and the addons it declares in uses](an-addon-may-reach-only-itself-and-the-addons-it-uses.md) — An RPC call that arrives tagged with an addon header is refused unless the target is the caller or one of the caller's declared uses, and an unknown addon name is refused outright
 - [An agent approval is claimed before the tool runs](an-agent-approval-is-claimed-before-the-tool-runs.md) — resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
+- [An API key is JWT-decoded into the session, from a header or a query parameter](an-api-key-is-jwt-decoded-into-the-session.md) — authAPIKey reads x-api-key or the apiKey query parameter, decodes it as a JWT, and sets the session only when no session exists yet
+- [An approval answer outlives the run it answered](an-approval-answer-outlives-the-run-it-answered.md) — Run state holds a decision only while the gate is open, so the settled answer carries decidedBy/decidedAt into the step result and every attempt is written to the audit sink, which has no foreign key to the run
 - [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
+- [An external virtual user caller presents one signed statement](an-external-virtual-user-caller-presents-one-signed-statement.md) — Callers outside the app sign an EdDSA statement naming the virtual user; the app verifies it against a public key and accepts each statement once
+- [An inbound webhook source dispatches only requests verified against its credential](an-inbound-webhook-source-dispatches-only-verified-requests.md) — A webhook source with verify refuses a body-carrying request that fails its check, fails closed on an empty secret, and does not dispatch events from a body-less request
+- [An MCP call with no HTTP request stays anonymous by transport design](an-mcp-call-with-no-http-request-stays-anonymous.md) — MCP calls that arrive without an HTTP request, such as stdio, reach the function with no session because auth middleware reads the session only from the request
 - [An MCP refusal is decided before dispatch, not raised from the tool](an-mcp-refusal-is-decided-before-dispatch.md) — mcpTargetRequiresSession lets the transport answer 401 with an OAuth challenge, because the MCP response streams and the status is gone by the time the runner refuses
 - [An OAuth2 credential is read by its account row, not by its provider name](an-oauth2-credential-is-read-by-its-account-row.md) — better-auth 1.7.5 selects an account by row id under a strict body schema, so BetterAuthCredentialService resolves the row through the internal adapter before asking for a token
-- [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
+- [An omitted userId on CredentialService addresses the platform credential](an-omitted-user-id-addresses-the-platform-credential.md) — The CredentialService contract reads and writes the platform-level credential whenever a per-credential call omits userId, and the better-auth implementation defaults its platform owner to pikku-platform
 - [An upload is counted as it arrives, not buffered and then measured](an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md) — Reading the whole body before checking its size hands an unauthenticated caller a way to spend the server's memory
+- [Analytics identity is stamped from the session and resolvers, never from the event body](analytics-identity-is-stamped-from-the-session-not-the-event.md) — 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
+- [App access is a scope tree synthesised from the virtual users that name an app](app-access-is-a-scope-tree-synthesised-from-virtual-users.md) — 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
+- [The approval policy decides who answers a tool call](approval-policy-decides-who-answers-a-tool-call.md) — 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
+- [auth false on a session-required function warns and still requires a session](auth-false-on-a-session-function-warns-and-still-requires-one.md) — 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
+- [Bearer token hashes are unpeppered SHA-256](bearer-token-hashes-are-unpeppered-sha256.md) — 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
+- [Consent is read from a cookie, and a recognised denial value counts as a refusal](consent-is-read-from-a-cookie-and-a-recognised-denial-counts-as-refusal.md) — 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
 - [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
+- [CORS defaults to any origin and refuses the wildcard when credentials are on](cors-defaults-to-any-origin-and-refuses-the-wildcard-with-credentials.md) — The cors middleware's origin defaults to *, and a resolved wildcard origin combined with credentials throws when the middleware is built
+- [Credential backends are checked by one conformance suite that proves per-user isolation](credential-backends-share-one-conformance-suite-for-per-user-isolation.md) — 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
+- [Each stage has one virtual user key pair, and the app holds only the public half](each-stage-has-one-virtual-user-key-pair.md) — The deployer holds the private key, the app reads the public key from an unreserved variable, and users never see either
 - [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
+- [HMAC verification fails closed on empty or malformed inputs](hmac-verification-fails-closed-on-empty-inputs.md) — verifyHmacSignature returns false for an empty secret, a missing signature, an unknown algorithm, an empty key, a malformed hex signature or an empty signature
 - [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
+- [Local content refuses private buckets under the public segment and paths outside the root](local-content-refuses-private-buckets-under-the-public-segment.md) — The local content path resolver returns no target for a private bucket whose first segment is the public URL segment, for NUL bytes, and for any path resolving outside its visibility root
+- [Mail reaches a virtual user run only after sender and link-origin allowlisting](mail-is-allowlisted-before-a-virtual-user-run-sees-it.md) — applyMailboxAllowlist keeps only mail from listed senders and drops links to unlisted origins; the engine ships no mailbox, so every implementation must call this helper
 - [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
+- [MCP resources, tools and prompts take sessionless functions, because an MCP client is not a logged-in user](mcp-resources-tools-and-prompts-take-sessionless-functions.md) — The MCP wiring types default each func to CorePikkuFunctionSessionless, so an MCP entry point is declared without a session type; whether a session is required is decided per function by the runner
+- [Origin-locked routes accept only an exact origin match and refuse a missing one](origin-locked-routes-match-the-origin-exactly.md) — requireOrigin rejects a request whose Origin, or Referer when Origin is absent, is not the host's own origin or a configured origin, compared by equality
+- [Open-source auth works without Pikku Studio Cloud](oss-auth-works-without-pikku-studio-cloud.md) — Every virtual-user sign-in path works in an app that runs no Pikku Studio Cloud code; the signing key is the project's own, never a cloud-issued credential
+- [Outbound webhooks use an allowlist when one is configured, and block private hosts otherwise](outbound-webhooks-use-an-allowlist-when-configured.md) — The webhook delivery reads allowedHosts from config and passes it to safeFetch; without an allowlist safeFetch refuses private hosts, and an allowlist replaces that check
 - [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
+- [Core carries virtual user roles as data and provisioning grants them](pikku-carries-virtual-user-scopes-as-data-and-the-app-grants-them.md) — roles on a resolved virtual user are transported by core, never applied there — provisionVirtualUsers grants them in the running stage, through the scope service the app wired
 - [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 scaffold flag says a surface exists, not who may call it](a-scaffold-flag-says-a-surface-exists-not-who-may-call-it.md) — scaffold.<feature> is boolean | { path }; the auth field is gone because the function runner already enforces each generated function's own auth, wiring, scopes and addon
-- [A scaffolded surface is authenticated unless the config opts out in writing](scaffold-features-are-authenticated-unless-opted-out.md) — SUPERSEDED; retains why the legacy 'auth' | 'no-auth' strings are refused rather than coerced
+- [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
-- [A public function says so with auth: false](a-public-function-says-so-with-auth-false.md) — An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
+- [Scoped content access is confined to a root folder, with longest-prefix grants outside it](scoped-content-access-is-a-root-folder-with-longest-prefix-grants.md) — ScopedContentService keeps an addon inside its root folder, lets it reach the wider store only through read or write grants matched by longest prefix, and refuses signURL and copyFile
 - [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
+- [Contexts that must not hold secrets get a services bag whose secrets accessor throws](services-without-secrets-get-a-throwing-secrets-accessor.md) — withoutSecrets replaces the secrets entry with a non-enumerable getter that throws, so code outside the permitted contexts cannot reach the secret service
+- [Shared guards refuse to mutate or shadow a system role, in every store](shared-guards-refuse-to-mutate-or-shadow-a-system-role.md) — system-role-guard holds the guards every ScopeService must call before changing a role, and roleLockReason gives the console a reason to show for a locked role
 - [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
+- [Signed uploads are verified by the same check as signed reads](signed-uploads-are-verified-by-the-same-check-as-signed-reads.md) — The local content handler refuses an upload whose presigned URL does not verify, using the same exported verifier that signed reads use
+- [System role scopes must be declared with defineScope, or the build fails](system-role-scopes-must-be-declared-with-define-scope.md) — A system role may grant only scope ids that defineScope declares, and the bare wildcard is refused; both are critical inspector diagnostics, so a role cannot grant a scope no function checks
+- [System roles are never deleted by a deploy, but their scope set follows the declaration, and the admin API cannot change them](system-roles-are-additive-and-immutable.md) — syncSystemRoles keeps a role row whose declaration has gone (marked declared false) but replaces a declared role's scope set; deleteRole and setRoleScopes refuse system roles
+- [The channel RPC does not put the caller's session on the wire](the-channel-rpc-does-not-send-the-callers-session.md) — ChannelDeploymentService.invoke accepts a session only to satisfy the DeploymentService shape and never sends it, so the peer runs the capability as itself
+- [The remote jobs inbox rejects every caller when its secret is unset](the-remote-jobs-inbox-fails-closed-without-a-secret.md) — remoteJobsSecret refuses all requests when the dispatch secret variable is empty, and compares the header in constant time when it is set
+- [The remote RPC gate fails closed and binds a token to one function](the-remote-rpc-gate-fails-closed-and-binds-the-token-to-its-function.md) — pikkuRemoteAuthMiddleware refuses a remote-RPC request unless the mesh token is audience pikku-remote, names the requested function, and carries a session that decrypts under the mesh secret
+- [The workflow status stream re-checks run ownership on every poll and closes when access is lost](the-workflow-status-stream-rechecks-ownership-on-every-poll.md) — streamWorkflowRunStatus asserts the run owner on each poll rather than once when the stream opens, and closes the channel when that check throws
+- [Two credentials resolving to one key must agree on whether they are per-user or singleton](two-credentials-on-one-key-must-share-a-read-mode.md) — buildCredentialResolutions throws when two credentials resolve to the same stored key but would be read in different modes, so one cannot silently serve the other's value
+- [Verified bearer claims are pass-through data that core never fills](verified-bearer-claims-are-pass-through-data-that-core-never-fills.md) — PikkuHTTP.authInfo is a typed slot for claims a host has already verified; core declares it and no core source assigns it from request headers
+- [The virtual user catalogue excludes any RPC scoped under virtualUser](virtual-user-catalogue-excludes-the-machinery-that-runs-virtual-users.md) — deriveCatalogue drops every function whose scope begins with virtualUser, so a virtual user holding those scopes cannot start runs, read findings or set schedules through the catalogue
+- [A virtual user's missing approval decision defaults to denied](virtual-user-conversation-missing-approval-decisions-default-to-denied.md) — Every pending tool call gets an explicit decision; an id the virtual user LLM omitted is denied, so a dropped field can never read as consent
+- [Virtual user run records are privileged, and reads are gated behind their own scope](virtual-user-run-records-are-gated-behind-a-read-scope.md) — The generated read RPCs carry virtualUser:read while starting a run carries virtualUser:run, because adversarial findings are working exploits with live ids
+- [Virtual user sign-in endpoints do not exist in production](virtual-user-sign-in-does-not-exist-in-production.md) — The plugin registers the statement, in-process and switcher endpoints only when the sign-in gate is open at construction, and creating a row is dev-only
+- [Virtual user sign-in has one door, reached two ways](virtual-user-sign-in-has-one-door.md) — Only the app's virtual user sign-in handler creates a virtual user session; runs reach it in-process and everything else reaches it with a signed statement
+- [Virtual user sign-in is proven by Set-Cookie, not a non-empty jar](virtual-user-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md) — HttpVirtualUser tracks its own signedIn flag and both VirtualUserSignIn implementations require the sign-in response itself to set a cookie, because a populated jar proves nothing
+- [Virtual user sign-in only works for virtual-user-flagged users](virtual-user-sign-in-only-works-for-virtual-user-flagged-users.md) — A virtual user statement mints sessions for user rows flagged virtual user and nothing else, so holding one never impersonates a real user
 - [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
+- [wireAddon expose selects the RPC surface, and a list may widen it](wire-addon-expose-selects-the-rpc-surface.md) — The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
 - [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
+- [Workflow helper functions are registered sessionless by declaration](workflow-helper-functions-are-sessionless-by-declaration.md) — Queue-worker helpers and the workflow sleeper get meta with sessionless true, so the runner requires a session for them only where their own auth flag says so
 - [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
-
+- [Scenario sessions are isolated per virtual user and reset between scenarios](workflow-scenario-sessions-are-isolated-per-virtual-user-and-per-scenario.md) — One jar per virtual user keeps two virtual users 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 a virtual user's session, so exposing it as an RPC would put that reach on the network
+- [A scenario virtual user step always goes over the real transport and never through internal dispatch](workflow-virtual-user-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
+- [Writing a virtual user schedule is gated by its own scope, separate from running one](writing-a-virtual-user-schedule-is-gated-by-its-own-scope.md) — setVirtualUserSchedule carries virtualUser:schedule, because a schedule write spends money on every future tick while a run spends it once with a caller watching
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/security/local-content-refuses-private-buckets-under-the-public-segment.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: Local content refuses private buckets under the public segment and paths outside the root
+description: The local content path resolver returns no target for a private bucket whose first segment is the public URL segment, for NUL bytes, and for any path resolving outside its visibility root
+tags: core, content, security
+---
+
+# Local content refuses private buckets under the public segment and paths outside the root
+
+The path resolver in `packages/core/src/services/local-content.ts:88-104` returns
+`null` (no target) in four cases:
+
+- the visibility is not one of the known visibilities (`:92`);
+- the bucket or key contains a NUL byte (`:93`);
+- the visibility is `private` and the bucket's first path segment is
+  `PUBLIC_URL_SEGMENT` (`:94-96`);
+- the scoped path or the final target resolves outside the visibility root
+  (`:98-102`). `inside` accepts only the root itself or a path under `root + sep`.
+
+**What this rules out:** reaching private content through the public URL segment,
+and a bucket or key with `..` or an absolute component escaping the root.

package/knowledge/decisions/security/mail-is-allowlisted-before-a-virtual-user-run-sees-it.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: Mail reaches a virtual user run only after sender and link-origin allowlisting
+description: applyMailboxAllowlist keeps only mail from listed senders and drops links to unlisted origins; the engine ships no mailbox, so every implementation must call this helper
+tags: core, virtual-users, email, prompt-injection
+---
+
+# Mail reaches a virtual user run only after sender and link-origin allowlisting
+
+`packages/core/src/wirings/virtual-user/virtual-user-mailbox.ts` defines the `VirtualUserMailbox`
+interface and the allowlist helpers.
+
+The interface doc says implementations "**must** apply `MailboxAllowlist` before
+returning anything", and calls this the primary defence against prompt injection,
+because a virtual user's address can be reached by anyone who learns it
+(`virtual-user-mailbox.ts:40-44`). The engine ships no mailbox: capturing mail is
+platform-specific, so pikku "declares the interface and ships no default"
+(`virtual-user-mailbox.ts:36-38`).
+
+`applyMailboxAllowlist` filters by sender and then trims each email's links
+(`virtual-user-mailbox.ts:150-156`). The doc comment says implementations should call
+it rather than filter themselves (`virtual-user-mailbox.ts:146-148`).
+
+- Sender: an entry with `@` must match the whole address. A bare domain must
+  equal the part after the last `@` (`virtual-user-mailbox.ts:91-101`). The comment
+  says a bare domain never matches as a substring (`virtual-user-mailbox.ts:97-98`).
+- Links: with no `linkOrigins`, every link is kept (`virtual-user-mailbox.ts:122-124`).
+  Otherwise a link is kept only when its origin is listed, and a link that does not
+  parse is dropped (`virtual-user-mailbox.ts:134-140`).
+- Links are filtered rather than the whole email rejected, because a legitimate
+  email may carry an unrelated unsubscribe link (`virtual-user-mailbox.ts:109-116`).
+
+The raw `body` is optional and is not meant to reach a model context
+(`virtual-user-mailbox.ts:25-29`).
+
+**What this rules out:** a virtual user run acting on mail from an unlisted sender, and
+following a link that leaves the origins the stage allowed. Nothing in this file
+checks that an implementation actually calls the helper.

package/knowledge/decisions/security/mcp-resources-tools-and-prompts-take-sessionless-functions.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: MCP resources, tools and prompts take sessionless functions, because an MCP client is not a logged-in user
+description: The MCP wiring types default each func to CorePikkuFunctionSessionless, so an MCP entry point is declared without a session type; whether a session is required is decided per function by the runner
+tags: core, mcp, auth, sessionless
+---
+
+# MCP resources, tools and prompts take sessionless functions, because an MCP client is not a logged-in user
+
+`packages/core/src/wirings/mcp/mcp.types.ts` types the three MCP wirings the same way. Each one's `func` defaults to `CorePikkuFunctionSessionless`:
+
+- `CoreMCPResource`: default at line 92, and the `func` field is commented "It is sessionless: an MCP client is not a logged-in user" at line 113.
+- `CoreMCPTool`: default at line 123, and the same comment at line 138.
+- `CoreMCPPrompt`: default at line 150, and the same comment at line 163.
+
+So an MCP entry point is declared without a session-carrying function type. The types do not say whether a particular MCP call needs a session. The per-function declaration does that: `mcpTargetRequiresSession`, described in [An MCP refusal is decided before dispatch, not raised from the tool](an-mcp-refusal-is-decided-before-dispatch.md), reads a `pikkuFunc` as always needing a session, and a sessionless function as needing one only where it sets `auth: true`.
+
+**What this rules out:** typing an MCP wiring's `func` as a session-carrying function, which would make the MCP surface look as if it always has a logged-in user behind it.

package/knowledge/decisions/security/origin-locked-routes-match-the-origin-exactly.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Origin-locked routes accept only an exact origin match and refuse a missing one
+description: requireOrigin rejects a request whose Origin, or Referer when Origin is absent, is not the host's own origin or a configured origin, compared by equality
+tags: core, middleware, security
+---
+
+# Origin-locked routes accept only an exact origin match and refuse a missing one
+
+`isAllowedOrigin` in `packages/core/src/middleware/require-origin.ts:25-33`
+returns false when the request has no origin (`:30`). It then accepts only an
+equal host origin (`:31`) or an equal configured origin after `toOrigin`
+normalisation (`:32`). There is no suffix or prefix match.
+
+The middleware takes `Origin` first and falls back to `Referer` (`:59-61`),
+derives the host origin from `host` and `x-forwarded-proto`, which defaults to
+`https` (`:63-65`), and throws `InvalidOriginError` when the check fails
+(`:72-75`). The doc comment at `:36-42` says this is not CORS: it rejects before
+the function runs, and a missing origin is rejected on purpose.
+
+**What this rules out:** matching origins by suffix, and accepting a request that
+carries neither `Origin` nor `Referer`.

package/knowledge/decisions/security/oss-auth-works-without-pikku-studio-cloud.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Open-source auth works without Pikku Studio Cloud
+description: Every virtual-user sign-in path works in an app that runs no Pikku Studio Cloud code; the signing key is the project's own, never a cloud-issued credential
+tags: services, auth
+---
+
+# Open-source auth works without Pikku Studio Cloud
+
+Virtual users and staged impersonation must all work in an open-source app with
+no Pikku Studio Cloud service and no cloud-issued token. The cloud may add its
+own way in, but nothing in core, the CLI or the better-auth service may require
+it.
+
+The code holds to this. A virtual user signs in either in-process
+(`inProcessSignIn`, no credential at all) or with a signed statement
+(`statementSignIn`), both in `packages/core/src/services/virtual-user-sign-in.ts`.
+The statement is signed with an Ed25519 key the project owns:
+`packages/cli/src/utils/virtual-user-signer.ts` generates it for `pikku dev`, or
+reads `VIRTUAL_USER_SIGNING_KEY` from whoever deploys the stage. The app is given
+only the public half, as `VIRTUAL_USER_VERIFY_KEY`
+(`packages/services/better-auth/src/virtual-user-plugin.ts`).
+
+**What this rules out:** any design where Pikku Studio Cloud is the issuer of the
+credential a virtual user presents. A signer that only exists in the cloud cannot
+be the basis for an open-source feature.