@pikku/core 0.12.143 → 0.12.144

package/knowledge/decisions/security/index.md

@@ -1,135 +0,0 @@
----
-type: overview
-title: Security decisions
-description: Who may do what in core — gates, defaults, and the failures they are chosen to cause
----
-
-# Security decisions
-
-A rule about who may do what, and which way it fails when it is unsure.
-
-<!-- pikku:knowledge-index -->
-- [A 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 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
-- [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 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
-- [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 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
-- [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
-- [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 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

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

@@ -1,38 +0,0 @@
----
-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-internal-error-details-are-double-gated-on-production.md

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

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

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

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

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

package/knowledge/decisions/security/outbound-webhooks-use-an-allowlist-when-configured.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Outbound webhooks use an allowlist when one is configured, and block private hosts otherwise
-description: 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
-tags: core, webhooks, ssrf, security
----
-
-# Outbound webhooks use an allowlist when one is configured, and block private hosts otherwise
-
-`WebhookServiceConfig.allowedHosts` in `packages/core/src/services/webhook-service.ts:33-44`
-says that when it is set only those hostnames may be delivered to, and when it is
-omitted private and internal hosts are blocked.
-
-`queue-webhook-service.ts:104-110` reads it from `config.webhook`, and falls back
-to no allowlist if the singletons are not initialised. The value is passed to
-`safeFetch` (`:112-122`).
-
-In `packages/core/src/utils/safe-fetch.ts:265-273`, an allowlist makes the check an
-exact hostname match, and the private-host refusal is in the `else` branch that only
-runs without an allowlist. So with an allowlist, a listed host is not refused for
-being private.
-
-**What this rules out:** delivering to a host outside a configured allowlist, and
-delivering to a private host when no allowlist is configured.

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

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

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

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

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

@@ -1,35 +0,0 @@
----
-type: decision
-title: Core carries virtual user roles as data and provisioning grants them
-description: 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
-tags: services
----
-
-# Core carries virtual user roles as data and provisioning grants them
-
-A virtual user's `roles` (and the `app` it signs into) are declared in
-`defineVirtualUsers` and carried on `ResolvedVirtualUser`
-(`packages/core/src/services/virtual-users-service.ts`) into the generated
-`virtualUserConfigs`. Nothing in core reads them to grant anything:
-`createHttpVirtualUsers` (`packages/core/src/services/http-virtual-users.ts`) only
-signs the virtual user in.
-
-The grant is performed by `provisionVirtualUsers`
-(`packages/services/better-auth/src/provision-virtual-users.ts`), which runs in the
-stage itself and calls `addUserToRole` / `addScopeToUser` on the `scopeService` the
-app passes in. Its doc comment says it is additive — it creates and grants, never
-deletes or revokes — and that it throws rather than grant a virtual user's roles to
-an address a real user already holds.
-
-Core cannot do the granting: which scope store exists, whether roles have been
-created, and what a role means are all the application's own. Worse, a framework
-that granted scopes from wherever it was handed a virtual user would be a framework
-that can escalate privileges as a side effect of signing in. Keeping the fields
-inert in core makes the grant an act performed deliberately, against a store the
-app wired.
-
-**What this rules out:** teaching `createHttpVirtualUsers` (or any core service)
-to call `ScopeService.addScopeToUser` / `addUserToRole` from these fields, and
-treating a role listed on a virtual user declaration as evidence that the account
-holds it. That evidence comes from reading the roles back
-([a virtual user whose roles drift from the declaration refuses to run](a-virtual-user-whose-roles-drift-from-the-declaration-refuses-to-run.md)).

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

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

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

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

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

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