@pikku/core 0.12.139 → 0.12.142

package/knowledge/decisions/security/a-secret-is-sent-only-to-the-hosts-it-declares.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: A secret may only be sent to the hosts its declaration names
+description: 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
+tags: core, secrets, egress
+---
+
+# A secret may only be sent to the hosts its declaration names
+
+`packages/core/src/services/secret-host-binding.ts` holds the check
+`assertSecretAllowedForHost`. It looks up the secret's definition by id and reads
+its `allowedHosts` (`secret-host-binding.ts:36-39`).
+
+- No `allowedHosts`, and `requireAllowedHosts` is set: throw
+  (`secret-host-binding.ts:41-44`).
+- No `allowedHosts`, and the flag is not set: allowed (`secret-host-binding.ts:45`).
+- `allowedHosts` present: the host must match at least one entry, or throw
+  (`secret-host-binding.ts:48-50`).
+
+Matching (`secret-host-binding.ts:18-26`) is case-insensitive. An entry is either
+an exact host or a single leading `*.` wildcard. The wildcard requires a
+non-empty label before the dot (`secret-host-binding.ts:23`), so `*.example.com`
+does not match `example.com` itself.
+
+The error message tells the author to add the host to `allowedHosts` on the
+`defineSecret` if the send is intended (`secret-host-binding.ts:11`).
+
+**What this rules out:** sending a secret to a host its declaration does not
+name, and a bare-domain match against a wildcard entry.

package/knowledge/decisions/security/a-step-can-name-an-identity-no-virtual-user-holds-through-per-call-headers.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A scenario step can name an identity no virtual user holds, through per-call headers
+description: ScenarioInvokeOptions.headers lets a step send an impersonation or shim header on one call, and a virtual-user run never gets that option
+tags: core, virtual-users, scenario
+---
+
+# A scenario step can name an identity no virtual user holds, through per-call headers
+
+`ScenarioInvokeOptions` in `packages/core/src/services/virtual-users-service.ts` says
+its headers are how "a step expresses an identity no declared virtual user can — an
+impersonation header, or one of the header-shim principals a credential scenario
+invents." `HttpVirtualUser.invokeRaw` passes them to `postRpc`
+(`packages/core/src/services/http-virtual-users.ts`), so they go out on that one call
+alongside the virtual user's session.
+
+The option belongs to the scenario author, who writes the steps and is trusted to
+say which identity a check needs. A virtual-user run does not get it. Its target in
+`packages/core/src/wirings/virtual-user/virtual-user-target.ts` calls
+`virtualUser.invokeRaw(rpcName, args)` with no options, so an adversarial run cannot
+add a header to reach an identity its virtual user does not hold.
+
+**What this rules out:** giving a virtual-user run a per-call header, and removing the
+option from scenario steps on the grounds that a declared virtual user should be the
+only identity a step can use.

package/knowledge/decisions/security/a-stopped-run-by-id-skips-the-ownership-check.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Stopping an agent run by its id skips the ownership check; interruptAgent is the checked path
+description: signalRunInterrupt is exported and performs no authorisation, while interruptAgent asserts the run's resource owner before it signals
+tags: core, agent, security
+---
+
+# Stopping an agent run by its id skips the ownership check; interruptAgent is the checked path
+
+`signalRunInterrupt` in `packages/core/src/wirings/agent/agent-interrupt.ts:227-236`
+looks up the run and aborts it, with no check on who is asking. Its doc comment at
+`:215-220` says so directly: anyone holding a `runId` can stop the run, and callers
+should use `interruptAgent` unless the run's ownership is already established.
+
+It is exported from the agent entry point (`packages/core/src/wirings/agent/index.ts:33`).
+
+`interruptAgent` in `packages/core/src/wirings/agent/agent-stream.ts:1061-1086`
+loads the run (`:1070`), asserts the resource owner with `assertResourceOwner`
+(`:1074-1082`), and only then calls `signalRunInterrupt` (`:1084`). The RPC wrapper
+calls `interruptAgent` (`packages/core/src/wirings/agent/agent-rpc.ts:98`).
+
+**What this rules out:** exposing `signalRunInterrupt` to a caller who has not
+resolved the run's owner, and reaching a run through its id alone on a request
+path.

package/knowledge/decisions/security/a-vault-secret-redacts-on-serialization-and-throws-on-coercion.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: A vault secret redacts when serialized and throws when coerced to a string
+description: 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
+tags: core, secrets, classification
+---
+
+# A vault secret redacts when serialized and throws when coerced to a string
+
+`packages/core/src/classification/secret-value.ts` wraps a vault value in
+`SecretValue`. The raw value sits in a private field (`secret-value.ts:37`) and
+is returned only by `reveal()` (`secret-value.ts:43-45`).
+
+Two paths out of the wrapper behave differently on purpose:
+
+- Structured serialization is redacted. `toJSON` and the Node inspect hook both
+  return `REDACTED`, which is `[secret]` (`secret-value.ts:5`, `47-53`). The doc
+  comment says an audit or log write "must stay honest about the field without
+  crashing the request" (`secret-value.ts:29-30`).
+- String coercion throws. `toString` and `Symbol.toPrimitive` both throw
+  `SecretCoercionError` (`secret-value.ts:55-61`). The comment says "a template
+  literal or concatenation is always a leak" (`secret-value.ts:31`).
+
+The `Safe<T>` type (`secret-value.ts:91-106`) rejects a `SecretValue` anywhere
+in a type, for sinks typed `any`, `unknown` or a free generic.
+
+**What this rules out:** reading a secret without calling `reveal()`, putting a
+secret into a template literal or string concatenation, and a logger that
+crashes on a secret field instead of redacting it.

package/knowledge/decisions/security/a-virtual-user-catalogue-entry-is-filtered-by-scope-and-approval-is-denied-by-default.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: Virtual users are offered calls by declared scope, and approval-gated calls are denied by default
+description: 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
+tags: core, virtual-users, scopes, approval
+---
+
+# Virtual users are offered calls by declared scope, and approval-gated calls are denied by default
+
+`packages/core/src/wirings/virtual-user/virtual-user.types.ts` defines the
+catalogue entry a virtual user is offered.
+
+The `scopes` field lists the scopes the session must hold to call the RPC, all of
+them (`virtual-user.types.ts:92-99`). The doc comment explains why scopes and not
+permission functions: a scope is "declared and checkable", while "a permission is
+arbitrary code whose verdict nobody can predict without running it"
+(`virtual-user.types.ts:95-97`).
+
+`approvalRequired` is documented as "denied by default" (`virtual-user.types.ts:89-90`).
+The filter in `virtual-user-catalogue.ts` enforces this. It drops an entry when
+`approvalRequired` is set and the caller has not passed `allowApprovalRequired`
+(`virtual-user-catalogue.ts:113`), and that flag defaults to `false`
+(`virtual-user-catalogue.ts:95`).
+
+The same filter drops any entry the session's scopes do not cover
+(`virtual-user-catalogue.ts:115-117`).
+
+**What this rules out:** a virtual user calling an approval-gated RPC unless the
+run explicitly allows it, and a permission function being used to decide what a
+virtual user can see.

package/knowledge/decisions/security/a-virtual-user-environment-fails-closed.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: A virtual user's sign-in is refused unless the environment is known and allowed
+description: 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
+tags: core, virtual-users, environments, security
+---
+
+# A virtual user's sign-in is refused unless the environment is known and allowed
+
+`virtualUserEnvironmentRefusal`
+(`packages/core/src/wirings/virtual-user/virtual-user-environments.ts`) fails
+closed when:
+
+- `PIKKU_ENV` is unresolved;
+- `PIKKU_ENV` names an environment the config does not know;
+- the environment is production and the virtual user's disposition is not
+  `PRODUCTION_DISPOSITION` (`accountable`);
+- the environment is not one the virtual user may target.
+
+`resolveVirtualUserEnvironments` leaves production environments out when a
+virtual user declares no `environments`. A virtual user reaches production only
+when someone has named it there. The build-time half is
+`virtualUserEnvironmentErrors`, which the doc comment says the inspector runs;
+the run-time half is re-checked because "the run check does not trust which
+artifact got deployed".
+
+The refusal is applied by `pikku virtual-user sync`
+(`packages/cli/src/functions/commands/virtual-user-sync.ts`), by the
+`pikku virtual-user` command (`packages/cli/src/functions/commands/virtual-user.ts`)
+and by `provisionVirtualUsers`
+(`packages/services/better-auth/src/provision-virtual-users.ts`).
+
+**What this rules out:** provisioning or signing in virtual users when the target
+environment is ambiguous, and a production stage that carries virtual users it was
+never meant to have.
+
+Runs are stricter: [A virtual user never runs against production](a-virtual-user-never-runs-against-production.md)
+refuses even the `accountable` disposition.

package/knowledge/decisions/security/a-virtual-user-never-runs-against-production.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: A virtual user never runs against production, whatever its disposition
+description: startVirtualUserRun and an enabling writeVirtualUserSchedule both refuse with a 403 in production, including for the accountable disposition; an unresolved environment counts as production
+tags: core, virtual-users, environments, security
+---
+
+# A virtual user never runs against production, whatever its disposition
+
+`refuseInProduction` (`packages/core/src/wirings/virtual-user/virtual-user-scaffold.ts:192`) throws a `ForbiddenError`, "Virtual users do not run against production", whenever the process is a production run. It has no disposition exception: `accountable`, which the virtual user environment check still accepts at sign-in in production, is refused here too.
+
+It is called from two places:
+
+- `startVirtualUserRun` (`virtual-user-scaffold.ts:232`), before the run record is created, so a refused run leaves no row.
+- `writeVirtualUserSchedule` (`virtual-user-scaffold.ts:410`), only when the row is or becomes enabled. Disabling a schedule, or editing one that is off, is still allowed in production so a leftover schedule can be stopped. A scheduled tick dispatches `runVirtualUser` through `rpc.invoke` (`packages/cli/src/functions/wirings/virtual-user/serialize-virtual-user-functions.ts:563-566`), and that function calls `startVirtualUserRun` (same file, line 337), so a due tick is refused as well.
+
+"Production" is decided by `isProductionRun` (`virtual-user-scaffold.ts:179`). The configured `PIKKU_ENV` environment wins when the project configures environments, and an unresolved environment counts as production. `NODE_ENV` decides only for a project that configures none.
+
+The sign-in environment rule is separate and unchanged. See [A virtual user's sign-in is refused unless the environment is known and allowed](a-virtual-user-environment-fails-closed.md): signing an `accountable` virtual user in against production is still allowed there, and starting a run is not.
+
+The tests are in `virtual-user-scaffold.test.ts`: "refuses every disposition in production", "the accountable disposition is refused in production too", "an accountable cadence is refused in production too" and "disabling or editing an off cadence is allowed in production".
+
+**What this rules out:** a virtual user, probing or not, acting on real customers' data, and an enabled schedule that can only ever fail to start in production.

package/knowledge/decisions/security/a-virtual-user-reads-its-roles-from-the-apps-own-rpc-before-better-auth.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A virtual user reads its roles from the app's own RPC before better-auth's user.role
+description: sessionRoles asks getMyScopes first, then get-session, and returns null rather than an empty list when the stage reports no roles
+tags: core, virtual-users, auth
+---
+
+# A virtual user reads its roles from the app's own RPC before better-auth's user.role
+
+`HttpVirtualUser.sessionRoles` (`packages/core/src/services/http-virtual-users.ts`) answers
+"what roles does this session hold" in a fixed order. First the app's exposed RPC,
+which defaults to `getMyScopes` and can be renamed or switched off with `rolesRpc`.
+Only then better-auth's `get-session`, where its admin plugin puts `role` on the
+user.
+
+The `rolesRpc` doc comment gives the reason. In an app that authorizes on scopes,
+`user.role` is "a projection rather than the model": it exists so better-auth's
+admin endpoints have something to read, and it may be absent. A virtual user verified
+against it is verified against a copy.
+
+Two answers are kept apart. A stage that answers neither returns `null`, which
+means "this stage does not report roles". A session that carries a user with no
+role field returns `[]`, which means "this person has none". The doc comment says
+the two call for opposite responses from the caller.
+
+**What this rules out:** making better-auth's `user.role` the first source of a
+virtual user's roles, and reporting `[]` for a stage that could not answer at all.

package/knowledge/decisions/security/a-virtual-user-run-treats-an-unresolved-environment-as-production.md

@@ -0,0 +1,41 @@
+---
+type: decision
+title: A virtual-user run treats an unresolved PIKKU_ENV as production
+description: 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
+tags: core, virtual-users, environments, security
+---
+
+# A virtual-user run treats an unresolved PIKKU_ENV as production
+
+`startVirtualUserRun` calls `refuseInProduction` before it creates a run record
+(`packages/core/src/wirings/virtual-user/virtual-user-scaffold.ts:232`). `PIKKU_ENV`
+is read as the default for `environment` (`virtual-user-scaffold.ts:217`). The
+schedule writer runs the same check when the schedule is or becomes enabled
+(`virtual-user-scaffold.ts:399`, `:409-411`).
+
+`refuseInProduction` throws a `ForbiddenError` whenever `isProductionRun` is true,
+whatever the disposition (`virtual-user-scaffold.ts:192-204`). That rule is
+[a virtual user never runs against production](a-virtual-user-never-runs-against-production.md);
+this note is about how "production" is decided.
+
+`isProductionRun` decides it as follows (`virtual-user-scaffold.ts:179-188`):
+
+- With no environments configured, it is `NODE_ENV === 'production'` (`:184-186`).
+- With environments configured and `PIKKU_ENV` unset, it is true (`:187`,
+  `environment ? ... : true`).
+- With `PIKKU_ENV` set, it is that environment's `production` flag (`:187`). An
+  unknown name evaluates to false in this check. `virtualUserEnvironmentRefusal`
+  refuses unknown names at sign-in instead
+  (`packages/core/src/wirings/virtual-user/virtual-user-environments.ts:113-119`).
+
+The comment gives the reasons. The configured environment wins over `NODE_ENV`
+because a production mirror runs `NODE_ENV=production` too
+(`virtual-user-scaffold.ts:166-172`). An unresolved environment counts as
+production because nobody can vouch for its data (`:174-177`).
+
+See also [a virtual user's sign-in is refused unless the environment is known and allowed](a-virtual-user-environment-fails-closed.md),
+which covers the sign-in refusal in `virtual-user-environments.ts`.
+
+**What this rules out:** starting a run when the environment cannot be named, and
+keying the scaffold's refusal on `NODE_ENV` in a project that has configured
+environments.

package/knowledge/decisions/security/a-virtual-user-scopes-are-expanded-from-its-roles-once-at-run-preparation.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A virtual user's scopes are expanded from its roles once, at run preparation
+description: 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
+tags: core, virtual-user, auth
+---
+
+# A virtual user's scopes are expanded from its roles once, at run preparation
+
+`virtualUserScopes` in `packages/core/src/wirings/virtual-user/prepare-virtual-user-run.ts`
+expands a virtual user's `roles` into scopes through the role definitions the seed
+grants from. Its doc comment says roles are the only thing a virtual user declares, and
+that the expansion happens "once, here, against the same `defineSystemRole`
+definitions the seed grants from".
+
+The result feeds two things in `run-virtual-user.ts`. It narrows the catalogue
+for a non-adversarial user, and it is the oracle: a call that succeeds on an
+endpoint whose `scopes` the virtual user does not hold is recorded as
+`unexpected-success`, which the code calls authorization drift. Using the static
+expansion as the truth is what makes that finding mean something, because the
+run never asks the target what the virtual user may do.
+
+**What this rules out:** building a virtual user's catalogue or judging its
+successes from a scope list fetched from the live session, which would make the
+oracle agree with whatever the target currently grants.

package/knowledge/decisions/security/a-virtual-user-whose-roles-drift-from-the-declaration-refuses-to-run.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: A virtual user whose granted roles drift from its declaration refuses to run
+description: verifyVirtualUserRoles compares declared and granted roles in both directions before a run, and roleMismatchMessage produces the refusal text; a provider login is never runnable
+tags: core, virtual-users, roles, drift
+---
+
+# A virtual user whose granted roles drift from its declaration refuses to run
+
+`packages/core/src/wirings/virtual-user/validate-virtual-users.ts` has the role check that
+runs before a virtual user's first step. `verifyVirtualUserRoles` computes what is missing
+and what is extra, in both directions (`validate-virtual-users.ts:94-111`). `roleMismatchMessage`
+returns `null` when they match, and otherwise a message that ends with "Refusing
+to run" (`validate-virtual-users.ts:114-133`, the text at `validate-virtual-users.ts:131`).
+
+The doc comment says the declaration is authoritative, but a run may target a
+stage that the generated seed never touched (`validate-virtual-users.ts:84-87`). It
+gives a reason for each direction: an under-granted virtual user reports seed drift
+as an authorization bug, and an over-granted one "silently stops testing the
+boundary it was written to test" (`validate-virtual-users.ts:89-92`).
+
+Nothing in `packages/core/src` calls `roleMismatchMessage`. The caller that
+stops the run is the `pikku virtual-user` command
+(`packages/cli/src/functions/commands/virtual-user.ts`), so this file only
+supplies the check and the message.
+
+`isRunnableVirtualUser` (`validate-virtual-users.ts:19-27`) returns false for a virtual user
+with `runnable: false`, and for any virtual user with an account provider, because
+driving a provider consent screen "needs a human" (`validate-virtual-users.ts:10-12`).
+
+**What this rules out:** running a virtual user whose roles no longer match what
+it declared, and a provider-login virtual user being driven by a run.

package/knowledge/decisions/security/addon-screen-scopes-hide-and-do-not-enforce.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: Addon screen scopes hide a screen and do not enforce access
+description: 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
+tags: core, addons, screens, security
+---
+
+# Addon screen scopes hide a screen and do not enforce access
+
+`packages/core/src/wirings/addon/define-screens.ts:7-8` documents `scopes` on an
+addon screen as required of the viewer to see it, and says the addon's functions
+must enforce the same scopes, because hiding a screen is not access control.
+
+The field is read statically by `pikku all`, which is why `scopes` must be a
+literal (`define-screens.ts:32`). Within `packages/core/src`, no code reads a
+screen's `scopes` at runtime; `wire-addon.ts:47-48` mounts the screens under
+`/addons/<name>` and is the only other place they are referenced.
+
+**What this rules out:** relying on a screen's scopes to keep data from a viewer,
+and an addon shipping a function that trusts the screen to have been hidden.

package/knowledge/decisions/security/an-addon-header-can-only-narrow-the-session.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: An addon header can only narrow the session, and an unknown addon is refused
+description: 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
+tags: core, middleware, scopes, addons
+---
+
+# An addon header can only narrow the session, and an unknown addon is refused
+
+`packages/core/src/middleware/addon-scope-cap.ts` reads the `x-pikku-addon`
+header (`addon-scope-cap.ts:8`, `31`). When a session is present, it resolves
+the addon's role and replaces the session's scopes with
+`intersectScopes(session.scopes, role)` (`addon-scope-cap.ts:37-45`).
+
+The doc comment says the header "is a selector, not a credential: naming an
+addon can only reduce a session" (`addon-scope-cap.ts:16-17`). An addon the host
+does not know throws `ForbiddenError` (`addon-scope-cap.ts:38-40`), because the
+comment says ignoring it "would let a misspelt name run uncapped"
+(`addon-scope-cap.ts:18-19`).
+
+With no header, or no session, the middleware calls `next()` and changes
+nothing (`addon-scope-cap.ts:33-34`). The comment says to register it after the
+session middleware (`addon-scope-cap.ts:21-22`).
+
+**What this rules out:** using the header to gain scopes, and treating an
+unrecognised addon name as "no cap".

package/knowledge/decisions/security/an-addon-instance-reads-only-the-secrets-and-credentials-it-is-named.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: An addon instance reads only the secrets and credentials it is named
+description: 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
+tags: core, addons, secrets, credentials
+---
+
+# An addon instance reads only the secrets and credentials it is named
+
+The consuming app decides which secrets and credentials an addon instance may
+read. The grant fields are declared on the wiring as "set by the consuming app"
+(`packages/core/src/wirings/rpc/rpc-types.ts:73-76`) and carried through
+`wireAddon` (`packages/core/src/wirings/addon/wire-addon.ts:123-126`) into the
+instance (`packages/core/src/wirings/addon/addon-runner.ts:20-22`).
+
+The allowed set is built by `allowedNames` in `addon-runner.ts:40-49`: the names
+the package declared, plus the grants, plus the keys of the overrides. An
+override key therefore grants the name; the override value is the key the
+lookup is pointed at. `wire-addon.ts:71` says the grant check runs before
+`secretOverrides` rename a name.
+
+Scoping is applied when the instance's services are built
+(`addon-runner.ts:200-227`). Unless `globalSecrets` is set, the secret service
+is wrapped in `ScopedSecretService`; unless `globalCredentials` is set, the
+credential service is wrapped in `ScopedCredentialService`. The global options
+hand over the unscoped service, and their value is a reason string
+(`wire-addon.ts:75-82`). The comments say the reason is recorded in the deploy
+manifest; that recording was not traced here.
+
+**What this rules out:** an addon reading a name neither it declared nor the
+host named, including through an override value; and an unscoped service
+reaching an addon without the consuming app setting a `globalSecrets` or
+`globalCredentials` reason.

package/knowledge/decisions/security/an-addon-may-reach-only-itself-and-the-addons-it-uses.md

@@ -0,0 +1,16 @@
+---
+type: decision
+title: An addon may reach only itself and the addons it declares in uses
+description: 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
+tags: core, addons, rpc, scopes
+---
+
+# An addon may reach only itself and the addons it declares in uses
+
+`addonMayReach` in `packages/core/src/wirings/addon/addon-reach.ts` takes the caller addon and the target function name (`addon-reach.ts:6`). It takes the target from the part of the name before `:` (`addon-reach.ts:7`). It returns `false` for an empty target (`:8`), `true` when the target is the caller (`:9`), and otherwise `true` only when the caller's declared `uses` includes the target (`:10-11`).
+
+`addonCallerOf` reads the addon header from the HTTP request (`addon-reach.ts:14-16`). A name that is not a registered addon is refused with `ForbiddenError` (`addon-reach.ts:17-18`).
+
+`ContextAwareRPCService.rpcExposed` applies the check before resolving the function. A caller that fails `addonMayReach` gets `AddonNotUsedError` (`packages/core/src/wirings/rpc/rpc-runner.ts:189-192`).
+
+**What this rules out:** an addon calling into another addon it does not declare in `uses`, and an addon header naming an unregistered addon being treated as anonymous rather than refused.

package/knowledge/decisions/security/an-api-key-is-jwt-decoded-into-the-session.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: An API key is JWT-decoded into the session, from a header or a query parameter
+description: 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
+tags: core, auth, middleware, api-keys
+---
+
+# An API key is JWT-decoded into the session, from a header or a query parameter
+
+`packages/core/src/middleware/auth-apikey.ts` takes an API key from the
+`x-api-key` header, the `apiKey` query parameter, or both, depending on the
+`source` option (`auth-apikey.ts:11-13`, `21-27`). The header is tried first;
+the query is read only when no header value was found (`auth-apikey.ts:25`).
+
+The key is decoded with `jwtService.decode` and, if that returns a value, passed
+to `setSession` (`auth-apikey.ts:29-33`). The middleware does nothing when a
+session already exists (`auth-apikey.ts:17`), which the doc comment describes as
+leaving "an existing session alone, so it composes with other auth middleware"
+(`auth-apikey.ts:6-7`).
+
+Nothing is decoded when no `jwtService` is wired (`auth-apikey.ts:29`).
+
+**What this rules out:** an API key overriding a session that is already set,
+and a key being accepted without a JWT service to verify it. The code also
+accepts a key from the query string (`auth-apikey.ts:26`), so keys can appear in
+URLs when `source` includes `query`.

package/knowledge/decisions/security/an-external-virtual-user-caller-presents-one-signed-statement.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: An external virtual user caller presents one signed statement
+description: 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
+tags: services
+---
+
+# An external virtual user caller presents one signed statement
+
+The statement is an EdDSA (Ed25519) JWT: `sub` is the virtual user id, `aud` is the
+app's origin, `iat`, `exp` a few minutes out (default 180 seconds, ceiling 300), and
+`jti`, a one-time id. The CLI signs it with `node:crypto`; the app verifies it with
+`JoseVirtualUserStatementVerifier` (`packages/services/jose`), `jwtVerify` pinned to
+`algorithms: ['EdDSA']`, against a public key. `POST /sign-in/virtual-user` takes
+`{ statement }`, maps `sub` to a declared virtual user, and signs it in.
+
+It is rejected for a wrong algorithm (`none` and HS256 included), a wrong key, a wrong
+audience, expiry, a lifetime beyond the ceiling, a missing `sub` or `jti`, and a `jti`
+already accepted. The replay store is a per-process map of `jti` to expiry, purged on
+each call, so it never outgrows the last few minutes of statements.
+
+One statement replaces three older credentials — a secret derived per virtual user from
+a root, an operator token with impersonation, and an app-wired sign-in hook — because
+each of them put something the app could mint a session from in the hands of a caller,
+or in the app's own configuration. A public key lets the app check a statement and
+nothing else; capturing the app's environment yields no ability to sign one.
+
+The **id-only dev switcher** (`/sign-in/switch-virtual-user`) is unchanged under
+`pikku dev`. Anywhere else it also needs a `statement` naming the same id, so no
+deployed stage has a credential-free way in.
+
+The statement endpoint needs the declared virtual users to map an id to an address, so
+it is registered only when the app passes `virtualUserSignIn.virtualUsers`, which the
+generated `virtualUserList` supplies.
+
+**What this rules out:** the app holding a private key, a statement without an
+expiry or one-time id, an algorithm negotiated by the token, and a switcher that works
+on a stage without proof.

package/knowledge/decisions/security/an-inbound-webhook-source-dispatches-only-verified-requests.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: An inbound webhook source dispatches only requests verified against its credential
+description: 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
+tags: core, webhooks, trigger, security
+---
+
+# An inbound webhook source dispatches only requests verified against its credential
+
+`verifyRequest` in `packages/core/src/wirings/trigger/webhook-source-runner.ts:173-200`
+decides whether a request counts as signed. A source with no `verify` returns
+true (`:178`). Otherwise the secret is read from the credential named by
+`source.credential`, or from `webhookSecretCredentialName` (`:180-182`).
+
+When the secret is missing or empty, a body-less request is treated as
+unverified (`:184`), and a request with a body throws `UnauthorizedError`
+(`:185-187`). `signedWith` also fails closed on an empty secret (`:127-128`).
+The token form compares with `timingSafeStringEqual` (`:153-155`), which is
+defined in `packages/core/src/utils/hmac.ts:57-63`.
+
+A mismatch on a request with a body throws (`:199`). A body-less request is not
+an error, but the runner refuses any events it produces: if `verified` is false
+and `receive` returned events, it throws `UnauthorizedError` (`:273-276`). The
+same contract is documented for authors at
+`packages/core/src/wirings/trigger/webhook-source.types.ts:130-135`, and the
+helper that runs the source's steps calls `runPikkuFunc` with `auth: false`
+(`webhook-source-runner.ts:96-101`), so the signature, not a session, is the
+gate.
+
+**What this rules out:** dispatching events from a body-carrying request that did
+not verify, and treating an empty signing secret as a valid key.

package/knowledge/decisions/security/an-mcp-call-with-no-http-request-stays-anonymous.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: An MCP call with no HTTP request stays anonymous by transport design
+description: 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
+tags: core, mcp, auth, transport
+---
+
+# An MCP call with no HTTP request stays anonymous by transport design
+
+`RunMCPEndpointParams.http` in `packages/core/src/wirings/mcp/mcp-runner.ts` is the HTTP request an MCP call arrived on (`mcp-runner.ts:39-41`, field at `:52`).
+
+The comment gives the mechanism. Auth middleware reads the session off `wire.http.request`, and every implementation returns early when there is no request (`mcp-runner.ts:42-46`). Without the request, an MCP call reaches the function unauthenticated whatever middleware is registered (`mcp-runner.ts:43-46`).
+
+The field is left undefined for transports with no request, such as stdio. The comment says those calls remain anonymous, and that this is a property of the transport rather than a default chosen in the runner (`mcp-runner.ts:48-50`).
+
+The surrounding decision about sessionless MCP entry points is in [MCP resources, tools and prompts take sessionless functions](mcp-resources-tools-and-prompts-take-sessionless-functions.md). The refusal for an HTTP call that needs a session is in [an MCP refusal is decided before dispatch](an-mcp-refusal-is-decided-before-dispatch.md).
+
+**What this rules out:** treating a request-less MCP call as carrying a session, and filling in a fake HTTP request to make middleware run for a stdio caller.

package/knowledge/decisions/security/an-omitted-user-id-addresses-the-platform-credential.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: An omitted userId on CredentialService addresses the platform credential
+description: 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
+tags: core, credentials, security, interface
+---
+
+# An omitted userId on CredentialService addresses the platform credential
+
+`CredentialService` in `packages/core/src/services/credential-service.ts` is the store for dynamic
+credentials such as OAuth tokens and per-user keys. Its doc comment says that throughout the interface,
+an omitted `userId` means the platform-level credential (`packages/core/src/services/credential-service.ts:4`).
+
+The per-credential methods take an optional `userId`: `get` (`credential-service.ts:7`), `set` (`:9`),
+`delete` (`:11`) and `has` (`:13`). Omitting it selects the platform credential, so the caller chooses
+the identity by whether it passes one.
+
+The methods that enumerate users are different. `getAll` requires `userId` (`credential-service.ts:15`),
+and `getUsersWithCredential` and `getAllUsers` take a credential name or nothing
+(`credential-service.ts:17` and `:19`). They do not have a platform default.
+
+The better-auth implementation applies the platform default only to some credentials. It takes an optional
+`platformUserId` that falls back to `PLATFORM_USER_ID` (`packages/services/better-auth/src/better-auth-credential.service.ts:58`).
+Its owner lookup returns null for a name that is not an OAuth2 credential (`better-auth-credential.service.ts:69-70`),
+returns that platform owner only for a singleton OAuth2 name (`better-auth-credential.service.ts:72-73`),
+and otherwise returns the `userId` passed in, or null when none was passed (`better-auth-credential.service.ts:75`).
+So for a non-singleton credential, an omitted `userId` reads as no owner, not as the platform credential. The
+interface comment describes the platform case more widely than this implementation does. Who may link the
+singleton is covered by [a singleton credential belongs to a reserved platform user](../../../../services/better-auth/knowledge/decisions/a-singleton-credential-belongs-to-a-reserved-platform-user.md).
+
+**What this rules out:** a sentinel string or an empty value to mean the platform credential, and relying on an
+omitted `userId` to reach the platform credential for a credential that is not a singleton.

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

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