@pikku/core 0.12.143 → 0.12.145

package/knowledge/decisions/security/a-channel-lifecycle-acts-as-the-socket-upgrade-session.md

@@ -1,16 +0,0 @@
----
-type: decision
-title: A channel lifecycle acts as the session the socket upgrade established
-description: 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
-tags: core, channel, sessions, lifecycle
----
-
-# A channel lifecycle acts as the session the socket upgrade established
-
-`runChannelLifecycleWithMiddleware` in `packages/core/src/wirings/channel/channel-common.ts` takes an optional `userSession`. The comment says it is established while the socket upgrades, so `onConnect` can tell who connected (`channel-common.ts:43-47`). The same function also serves `connect` and `disconnect` (`channel-common.ts:38`).
-
-The wire for the lifecycle is built from that session when one exists (`channel-common.ts:78`). The lifecycle function then runs through `runPikkuFunc` with `sessionService: userSession` (`channel-common.ts:84-93`). So the lifecycle reads and writes the same session the upgrade produced, for both connect and disconnect.
-
-The related decision that records when the user id is stored is [a channel's user id is persisted only after onConnect middleware has run](../internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md).
-
-**What this rules out:** running a channel's disconnect handler as a different identity than the one that connected the socket, and building the lifecycle wire without the upgrade session when one was established.

package/knowledge/decisions/security/a-channel-requires-a-session-unless-it-says-auth-false.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: A channel requires a session unless it says auth: false
-description: 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
-tags: core, channel, auth
----
-
-# A channel requires a session unless it says auth: false
-
-Both channel runners compute the channel-level requirement as
-`channelConfig.auth !== false`: `packages/core/src/wirings/channel/channel-runner.ts:142`
-and `packages/core/src/wirings/channel/channel-handler.ts:75`. An absent `auth`
-therefore requires a session. `channel.types.ts:67-76` documents the same rule and
-says why: a proxy in front of a channel needs to tell public from private.
-
-Per message, `validateAuth` (`channel-handler.ts:49-65`) uses the channel's
-`requiresSession` when the handler is a bare function or has no `auth` of its own
-(`:50-58`). When the handler object sets `auth`, that value wins (`:58-60`). The
-check then fails only when `auth` is true and there is no session (`:62-64`).
-
-So a message handler's `auth: false` loosens a channel that requires a session for
-that message, and `auth: true` tightens a public channel for that message. A
-rejected message gets the reply described in the question
-`unauthorized-channel-replies-escape-the-declared-out-type.md`.
-
-**What this rules out:** treating a channel with no `auth` flag as public.

package/knowledge/decisions/security/a-credential-read-path-follows-its-declared-type-not-absence.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: A credential's read path follows its declared type, never a missing value
-description: 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
-tags: core, credentials, wire, singleton
----
-
-# A credential's read path follows its declared type, never a missing value
-
-`packages/core/src/services/credential-wire-service.ts` decides where each
-credential is read from. The doc comment says the choice is "decided by what the
-credential IS — its declared type, as the wiring may have overridden it — and
-never by whether a per-user lookup came back empty", because an absence-driven
-fallback "would let a user who has not connected read the deployment's own token"
-(`credential-wire-service.ts:6-10`).
-
-The resolution type is `{ mode: 'wire' } | { mode: 'singleton' }`
-(`credential-wire-service.ts:12`).
-
-In `doLoad`, the user's store is read with `getAll(userId)`, and any name the
-resolution marks `singleton` is skipped (`credential-wire-service.ts:103-104`).
-The comment says this stops a user "in charge of a slot the deployment owns"
-(`credential-wire-service.ts:116-121`).
-
-`loadDeploymentCredentials` fetches only `singleton` names from the deployment
-service (`credential-wire-service.ts:137-143`). A `wire` name is skipped there
-(`credential-wire-service.ts:138`), and the comment says a wire credential "can
-never pick up a platform value" (`credential-wire-service.ts:127-130`).
-
-**What this rules out:** a `wire` credential falling back to the deployment's
-value when the user has none, and a user's stored value being imported under a
-name the deployment declared as `singleton`.

package/knowledge/decisions/security/a-credential-type-is-a-literal-the-inspector-checks-at-declaration.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: A credential's wire or singleton type is a literal the inspector checks at declaration
-description: 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
-tags: core, credentials, inspector, declaration
----
-
-# A credential's wire or singleton type is a literal the inspector checks at declaration
-
-`defineCredential` in `packages/core/src/wirings/credential/define-credential.ts` is a
-no-op. Its doc comment says the CLI reads the call by AST, so "the declaration must
-be a top-level literal" (`define-credential.ts:4-5`). `type: 'wire'` is per-user and
-`type: 'singleton'` is platform-wide (`define-credential.ts:6`).
-
-The inspector finds the call by its identifier (`packages/inspector/src/add/add-credential.ts:27`)
-and requires a `type` property. Anything other than `'singleton'` or `'wire'` is a
-critical error: "missing or has invalid 'type' property. Must be 'singleton' or
-'wire'" (`add-credential.ts:64-68`).
-
-The read path that follows from that type is in
-[a credential's read path follows its declared type, never a missing value](a-credential-read-path-follows-its-declared-type-not-absence.md).
-This note covers the declaration only: the type is decided where the credential is
-declared, and the inspector rejects a declaration whose type is missing or not one of
-the two literals.
-
-**What this rules out:** computing a credential's type from a variable or at runtime,
-and accepting a declaration whose type is missing or spelled differently.

package/knowledge/decisions/security/a-dropped-audit-write-is-always-logged.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: A dropped audit write is always logged
-description: The no-op audit service falls back to the singleton logger when the wire carries none, so an unconfigured audit call is never silent
-tags: services
----
-
-# A dropped audit write is always logged
-
-The no-op `AuditService` in `packages/core/src/services/audit-service.ts` is what
-a function gets when it calls `audit.write()` without `audit: true` set on it.
-Its `write` discards the event — but before it does, it warns once, and it looks
-for a logger in two places: the wire's own, then the singleton passed to the
-constructor.
-
-The fallback is the point. `wire.logger` is an optional hook for a host that
-wants invocation-scoped logging — core never sets it, so on every path core
-itself drives, the singleton is the only source there is. With only
-`this.wire.logger` the warning would be dropped every time.
-An audit call that silently does nothing is the worst available outcome: the
-function believes it is producing an audit trail, the trail does not exist, and
-nothing anywhere says so. The warning names the function and the fix, and fires
-once per instance so it cannot flood a hot path.
-
-**What this rules out:** narrowing the logger lookup to a single source,
-downgrading the warning to `debug`, or removing it as noise from a service whose
-whole job is to do nothing. If this class stops warning, an unconfigured audit
-call becomes undetectable.

package/knowledge/decisions/security/a-first-party-cookie-is-written-only-after-its-purposes-consent.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: A first-party tracking cookie is written only after its purposes are consented
-description: 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
-tags: core, analytics, consent, cookies
----
-
-# A first-party tracking cookie is written only after its purposes are consented
-
-`packages/core/src/analytics/mint-cookie.ts` creates a first-party cookie when
-none exists. The doc comment says writing the cookie "IS the act consent governs",
-so a minter that runs before the banner is answered has already done what the
-send gate was meant to prevent (`mint-cookie.ts:11-15`).
-
-The consent check is `permitted`. It returns true when no purposes are required,
-and otherwise requires each purpose to be exactly `true` in the consent record
-(`mint-cookie.ts:29-35`). A purpose missing from the record counts as refused.
-`mintCookie` runs that check after it has found no existing cookie and no cached
-value (`mint-cookie.ts:72`).
-
-An existing cookie is returned before the consent check (`mint-cookie.ts:63-64`).
-Reading a cookie the visitor already holds is therefore not gated by consent. The
-`overwrite` option is the only way to replace it (`mint-cookie.ts:19-26`).
-
-A wire with no HTTP response returns `undefined` and writes nothing
-(`mint-cookie.ts:70-71`), as the doc comment says for cron tasks and queue workers
-(`mint-cookie.ts:50-53`).
-
-The value is cached per wire, so a second call in one request returns the same
-identity (`mint-cookie.ts:66-68`, `77`, and the comment at `mint-cookie.ts:46-48`).
-
-**What this rules out:** writing a tracking cookie before its purposes are
-consented, and minting an identity on a non-HTTP wire.

package/knowledge/decisions/security/a-function-never-receives-the-secret-service.md

@@ -1,37 +0,0 @@
----
-type: decision
-title: A function never receives the secret service
-description: 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
-tags: services
----
-
-# A function never receives the secret service
-
-`SecretlessServices<Services>` is `Omit<Services, 'secrets'>`
-(`packages/core/src/types/core.types.ts`), and
-`CoreSecretlessSingletonServices` built from it is the constraint every
-function-, permission- and auth-facing type is bounded by
-(`packages/core/src/function/functions.types.ts`). Destructuring `secrets`
-inside a `pikkuFunc` body does not lint — it does not compile.
-
-The rule itself is older than the type: a function holding a `SecretService` can
-read every secret in the vault, which makes its blast radius the whole vault
-rather than the one credential it needs, and makes "which secrets does this
-function depend on?" unanswerable. `[PKU950]` enforces the same confinement for
-a `SecretService` reaching a function under an alias, because a rename does not
-change what it is. Encoding it in the type is what makes the honest mistake
-impossible rather than merely reported: secrets are resolved where things are
-constructed — `pikkuServices`, `pikkuWireServices`, addon service factories,
-middleware — and the function is handed the configured client.
-
-The cost is that a function which needs to _ask about_ a secret rather than read
-one — "is this key set?", for a readiness or provisioning check — cannot do it
-directly either. It goes through a service that holds `secrets` and exposes only
-that question, which is how `@pikku/addon-console` checks whether an installed
-addon's declared secrets are present.
-
-**What this rules out:** widening a function's services type back to
-`CoreServices` for a function that "only needs one secret", and passing the
-secret service through under another name — the type follows the shape and
-`[PKU950]` follows the type. It also rules out treating the absence as an
-oversight to be patched with a cast.

package/knowledge/decisions/security/a-graph-run-starts-at-an-entry-node-the-graph-declared.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: A graph run starts at an entry node the graph declared
-description: 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
-tags: workflow
----
-
-# A graph run starts at an entry node the graph declared
-
-`runWorkflowGraph` in
-`packages/core/src/wirings/workflow/graph/graph-runner.ts` takes an optional
-`startNode`. It used to accept any node id the graph contained, validated only
-by `validateGraphReferences` (does the node exist) and `areDependenciesSatisfied`
-(does its input reference another node). A node whose input is a literal or comes
-from the trigger passes both — including a node that is only ever reached after a
-validation, payment or approval node. Choosing it as the start does not skip the
-gate so much as never reach it.
-
-`startNode` is now checked against `meta.entryNodeIds`, the set the graph itself
-declared, and the generated `POST /workflow/:workflowName/graph/:nodeId` route
-that offered it to HTTP callers is gone.
-
-The parameter stays, because it has a real internal user: `PikkuTriggerService`
-(`packages/core/src/wirings/trigger/pikku-trigger-service.ts`) passes a target's
-`startNode` when a trigger fires. That caller names a node the graph declared, so
-the restriction costs it nothing.
-
-**What this rules out:** re-exposing entry-node choice on a generated route, and
-"validating" a `startNode` by existence or by dependency satisfaction — neither
-says the graph meant that node to be an entry point. It does not rule out a graph
-declaring several entry nodes; that is exactly how a graph says which starts are
-legitimate. If a graph needs a start that is not an entry node, the answer is to
-declare it as one, not to widen the check.

package/knowledge/decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: A permission gets a wire it cannot reply on
-description: 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
-tags: core, permissions
----
-
-# A permission gets a wire it cannot reply on
-
-`CorePikkuPermission` in `packages/core/src/function/functions.types.ts` types
-its wire as `PikkuWire<In, never, false, any, PikkuRPC, never, never>`. The
-second parameter is `Out`, and `never` there is deliberate: it makes
-`wire.channel` a `PikkuChannel<unknown, never, …>`, whose `send` accepts
-nothing. A permission is a gate — it answers `true` or `false` — and must not
-be able to write a reply to the caller it is deciding about. A permission that
-could `send` would be able to leak the very data the gate exists to withhold,
-and it would do so before the function it guards has run.
-
-`runPikkuFunc` holds an ordinary `PikkuWire`, whose default `Out` is `unknown`.
-`unknown` is not assignable to `never`, and `send` is contravariant in its
-argument, so the narrowing cannot be expressed as a subtype relation — the call
-into `runPermissions` asserts to the exact permission-wire type rather than
-relying on assignability.
-
-**What this rules out:** widening `Out` on the permission wire to `unknown` to
-delete the assertion. That silently hands every permission function a working
-`channel.send`. It equally rules out replacing the assertion with `as any`,
-which erases the target type and hides the fact that a specific, intentional
-narrowing is happening.
-
-The same reasoning explains the `never` in the fifth and sixth positions
-(`MCPTools`, `IsChannel`): a permission is not an MCP tool host and does not own
-the channel lifecycle.

package/knowledge/decisions/security/a-public-function-says-so-with-auth-false.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: A public function says so with auth: false
-description: An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
-tags: authorization, inspector, rpc
----
-
-# A public function says so with auth: false
-
-PKU574 warns about an exposed sessionless function with no gate. Some of those
-are exactly what the author meant: a published programme, a price list, a health
-check. Before this, the only way to quiet the warning on one was a gate that
-gated nothing — an always-true permission, or `permissionsInBody: true`, which
-claims a check the body does not make. Both put a false statement into meta to
-silence a true one, and the alternative, living with the warning, teaches
-everyone to stop reading it.
-
-`auth: false` is already the field that says "no session required". Writing it
-on a `pikkuSessionlessFunc` is redundant at runtime — sessionless already means
-that — which is what makes it useful as a declaration: nobody writes it by
-accident, so its presence is the author deciding the function is public. The
-inspector now records `auth` as written (`true`, `false` or absent) instead of
-folding `false` into absent, and the check treats `false` as a gate the author
-declared, the same way it treats `permissionsInBody`.
-
-The case the warning exists for is unchanged. A sessionless function that picked
-up `expose: true` later, with nobody thinking about who may call it, has no
-`auth` at all — and still warns.
-
-**What this rules out:** a separate `public: true` flag, which would be a second
-field meaning what `auth: false` already means; reading `readonly` or the
-function's name as evidence it is safe to expose; and silencing PKU574 for every
-sessionless function, which would drop the accidental-exposure case with the
-intentional one.

package/knowledge/decisions/security/a-readonly-session-reaches-only-readonly-functions.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A readonly session reaches only functions declared readonly
-description: A session flagged readonly is refused by every function not declared readonly, checked straight after the session is required and before scopes
-tags: core, auth, function-runner
----
-
-# A readonly session reaches only functions declared readonly
-
-`CoreUserSession.readonly` (`packages/core/src/types/core.types.ts`) restricts a
-session to functions declared `readonly`. In `runPikkuFunc`
-(`packages/core/src/function/function-runner.ts`) the check is
-`if (session?.readonly && !funcMeta.readonly) throw new ReadonlySessionError()`.
-It runs after the missing-session check and before scopes, permissions and input
-validation, so a readonly session is refused before any work is done for a
-mutating function. The unit test "should reject readonly sessions for
-non-readonly functions" in `function-runner.test.ts` pins the behaviour.
-
-Core never sets the flag. Whoever builds the session decides it, and core only
-enforces it. Readonly is a property of the session, not of a scope, so a scope
-grant cannot widen what a readonly session may reach.
-
-**What this rules out:** expressing read-only access as a scope the session
-happens to lack, and letting a readonly session call a mutating function on the
-grounds that its scopes cover it.

package/knowledge/decisions/security/a-scaffold-flag-says-a-surface-exists-not-who-may-call-it.md

@@ -1,52 +0,0 @@
----
-type: decision
-title: A scaffold flag says a surface exists, not who may call it
-description: 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
-tags: config, authorization, codegen, scaffold
----
-
-# A scaffold flag says a surface exists, not who may call it
-
-`scaffold.<feature>` carried an `auth` field, defaulting closed — see
-[[scaffold-features-are-authenticated-unless-opted-out]], which this supersedes.
-The field is gone. `PikkuScaffoldFeature` is now `boolean | { path?: string }`:
-whether the surface is generated, and where the file goes.
-
-The field was a second gate in front of one that already runs. `resolveSession`
-in `packages/core/src/function/function-runner.ts` (line 64) only loads a stored
-session; it throws nothing. The refusal is in `executeFunction`: a `pikkuFunc`
-with no session throws `MissingSessionError` (line 402, class at
-`packages/core/src/errors/errors.ts:36`), unconditionally. A
-`pikkuSessionlessFunc` throws the same error (line 392) only when its own
-`auth: true` says so, when its wiring says so, or when `resolveAddonAuth` does. That is where authentication is decided, per function,
-by whoever wrote it. Neither refusal is a `ForbiddenError`: both throw `MissingSessionError`
-(`function-runner.ts:392`, `:402`; class at `packages/core/src/errors/errors.ts:36`). The split between
-that error, `MissingScopeError` and `ForbiddenError` is recorded in
-[a call without a session raises MissingSessionError](./a-call-without-a-session-raises-missing-session-not-forbidden.md). A config flag three directories away could only be coarser
-than that, and being coarser was the whole problem the earlier decision was
-trying to work around by defaulting it closed.
-
-So the generated dispatchers — public RPC, public agent, workflow routes and the
-events channel — emit a fixed `auth: false` on every function and wiring they
-write. That is not the scaffold declaring the surface public. It is the
-dispatcher declining to gate, because it does not know what it is forwarding to:
-`rpcCaller` hands whatever name it was given to `rpc.exposed`, and the function
-that resolves there is the one that answers for itself. Omitting the field would
-not have been neutral — a wiring with no `auth` requires a session — so the
-wrapper would reject the call before the gate that decides ever ran, which is a
-harder gate than the config field it replaced, applied by the layer least
-qualified to apply it.
-
-The scoped admin surfaces do not emit it. `userAdmin` and `virtualUser` generate
-`pikkuFunc` with `scopes: ['admin:users:...']` — session-required by
-construction, and the function that decides rather than a wrapper in front of
-one. `auth: false` there is refused by `runPikkuFunc` with a warning telling you
-to use `pikkuSessionlessFunc` instead, and `auth: true` would only restate the
-type.
-
-`pikku enable <feature>` lost its `--noAuth` flag with the field it wrote.
-
-**What this rules out:** reading a scaffold flag as an authorization decision;
-gating a surface in the config instead of on the function that answers it; and
-letting a generated dispatcher inherit the default `auth: true`, which reads as
-"undecided" and behaves as "denied".

package/knowledge/decisions/security/a-scheduled-virtual-user-run-needs-no-admin-at-run-time.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: A scheduled virtual-user run needs no admin at run time
-description: 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
-tags: services, auth, workflow
----
-
-# A scheduled virtual-user run needs no admin at run time
-
-The people who set up virtual-user runs are not technical. A run must keep
-working after they stop being around, and it must not depend on any admin being
-signed in or on any admin's credential.
-
-An admin clicking "run" or creating a schedule is the authorization step. Once
-the schedule exists, the run is started by the app's own scheduler and performs
-the test as a provisioned test account (see
-[virtual-user-flagged users only](virtual-user-sign-in-only-works-for-virtual-user-flagged-users.md)).
-
-The run presents no credential at all. `executeVirtualUserRun`
-(`packages/core/src/wirings/virtual-user/virtual-user-scaffold.ts`) builds its
-virtual users with `signIn: inProcessSignIn(auth)`, which calls the app's
-server-only sign-in endpoint through `auth.api`
-(`packages/core/src/services/virtual-user-sign-in.ts`). The code asking is the
-app, so there is no key for an admin to hold or refresh.
-
-**What this rules out:** a run that borrows an admin's session or key, and a run
-that depends on a person to refresh a credential.

package/knowledge/decisions/security/a-scoped-credential-view-is-limited-to-declared-names.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: A scoped credential service is limited to the names its package declared
-description: ScopedCredentialService refuses any credential name outside the package's declared set, filters getAll to that set, and refuses to enumerate users
-tags: core, credentials, scoping
----
-
-# A scoped credential service is limited to the names its package declared
-
-`packages/core/src/services/scoped-credential-service.ts` wraps a
-`CredentialService` with the set of names a package declared. The doc comment
-says it "cannot reach a credential it never declared, or enumerate the app's
-users" (`scoped-credential-service.ts:6-9`).
-
-- `get`, `set`, `delete`, `has` and `getUsersWithCredential` each call
-  `assertAllowed` and throw `Access denied to credential` for an undeclared name
-  (`scoped-credential-service.ts:16-20`, `23`, `28`, `33`, `38`, `54`).
-- `getAll(userId)` returns only the declared names that the user holds
-  (`scoped-credential-service.ts:42-51`).
-- `getAllUsers` always throws (`scoped-credential-service.ts:58-62`).
-
-Writes are allowed for declared names (`scoped-credential-service.ts:27-30`), per
-the doc comment at `scoped-credential-service.ts:6-8`.
-
-**What this rules out:** a package reading or writing another package's
-credential, and a package listing every user of the app.

package/knowledge/decisions/security/a-scoped-secret-view-reads-only-declared-keys-and-never-writes.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A scoped secret view reads only its declared keys and never writes
-description: ScopedSecretService checks every read against an allowed-key set and refuses all writes, unlike the credential service that stays writable
-tags: core, secrets, scoping
----
-
-# A scoped secret view reads only its declared keys and never writes
-
-`packages/core/src/services/scoped-secret-service.ts` wraps a `SecretService`
-with a set of allowed keys (`scoped-secret-service.ts:4-8`).
-
-Every read is checked first. `getSecret`, `hasSecret` and `getSecrets` each call
-`assertAllowed`, which throws `Access denied to secret key` for any key outside
-the set (`scoped-secret-service.ts:10-14`, `17`, `22`, `43`).
-
-Every write is refused. `setSecret`, `setEncryptedSecret` and `deleteSecret`
-throw unconditionally (`scoped-secret-service.ts:26-38`).
-
-The credential counterpart is different. `scoped-credential-service.ts` says it
-"stays writable — an addon refreshing its own OAuth token is the normal case"
-(`scoped-credential-service.ts:6-8`).
-
-**What this rules out:** an addon reading a secret it did not declare, and an
-addon writing or deleting any secret through this view.

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

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

@@ -1,25 +0,0 @@
----
-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-step-runs-the-function-the-workflow-dispatched-it-with.md

@@ -1,37 +0,0 @@
----
-type: decision
-title: A step runs the function the workflow dispatched it with
-description: 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
-tags: workflow
----
-
-# A step runs the function the workflow dispatched it with
-
-`pikkuWorkflowStepWorker` (`workflow-queue-workers.ts`) takes `rpcName` straight
-off the queue message and hands it to `executeWorkflowStep`. That call runs as
-the run's owner — `invokeStepRpc` copies `run.wire.pikkuUserId` onto the wire —
-and `rpcWithWire` does not apply the `expose` gate that the public `/rpc` route
-applies. So the message decided both _what_ ran and _as whom_.
-
-The claim in `executeWorkflowStepInner` read the step's status and nothing else;
-there was no stored function name to compare against. `StepState` now carries
-`rpcName`, written by `insertStepState` (which already received it) and returned
-by every backend, and the claim rejects a message naming anything else with
-`WorkflowStepFunctionMismatchError` — before any status is mutated, so a forged
-message leaves the run untouched. The graph path takes the same value from
-`nodes[nodeId].rpcName` rather than from the message.
-
-`rpcName: undefined` means a store that never recorded one and cannot be
-compared; `null` is a step with no function of its own. Only a recorded value is
-checked.
-
-**Reachability, stated plainly:** the step-worker queue is not reachable from the
-public `/rpc/:rpcName` route — the worker is registered without `expose`. The
-exposure this closes is write access to the queue backend, and any in-process
-caller reaching `executeWorkflowStep` directly.
-
-**What this rules out:** trusting a queue payload to name the function it
-executes, here or in any future worker, and dropping `rpcName` from `StepState`
-as redundant with the step data — the comparison is the only thing standing
-between queue-write access and running any registered function as the run's
-owner.

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

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

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