@pikku/core 0.12.72 → 0.12.77

package/knowledge/decisions/security/workflow-queued-steps-rehydrate-their-session-from-the-run-wire.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: A queued workflow step rehydrates its session from the persisted run wire
+description: The queue job payload is just `{ runId }`, so without threading `pikkuUserId` an authed step sees no session and throws
+tags: workflow
+---
+
+# A queued workflow step rehydrates its session from the persisted run wire
+
+A queued workflow step is executed with the bare job wire — the payload is just
+`{ runId }` (or `{ runId, stepName, rpcName, data, fromStepName }`) — so it
+carries no `pikkuUserId`. `invokeStepRpc` in `pikku-workflow-service.ts`
+therefore merges the run's own `wire.pikkuUserId` into the step wire override
+before calling `rpcWithWire`. Without it, a step written as an authed
+`pikkuFunc` sees no session and fails with "Authentication required" on the
+queued path while passing inline, which is the worst possible split: it looks
+like a transport bug rather than an auth one.
+
+`invokeStepRpc` is shared by the queue executor and the inline executor
+precisely so the two cannot drift. The only thing that differs between
+transports is who calls it, not the call itself. `createWorkflowWire` and
+`runWorkflowJobInner` propagate the same `pikkuUserId` onto the workflow wire
+for the workflow body.
+
+The user id is the only identity carried. It is a reference for credential
+resolution, not a serialized session — the session itself is rehydrated on the
+far side.
+
+**What this rules out:** giving the queued path its own invocation helper,
+dropping the `pikkuUserId` merge because "the wire already has a session"
+inline, or widening the run wire to persist session tokens instead of a user id
+reference.

package/knowledge/decisions/security/workflow-scenario-sessions-are-isolated-per-actor-and-per-scenario.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: Scenario sessions are isolated per actor and reset between scenarios
+description: One jar per actor keeps two personas from sharing a session; a browser reset keeps one scenario from leaving the next signed in as somebody else
+tags: workflow
+---
+
+# Scenario sessions are isolated per actor and reset between scenarios
+
+`createCookieJar` in `scenario-cookie-jar.ts` holds its `Map` as a closure
+local, so two jars can never share a session. That is precisely what lets one
+scenario sign in as several people without one of them inheriting another's
+session. Every response is read, not just the sign-in, so a cookie the target
+rotates mid-session is followed rather than dropped, and an empty `Set-Cookie`
+value is treated as a deletion — the name is dropped rather than held as a
+cookie whose value says it is gone. The jar also stamps `Origin`, because Better
+Auth rejects a state-changing POST whose Origin does not match its baseURL.
+
+`ScenarioCookieJar.empty` reports a fact about the jar, not about the session: a
+target that sets a CSRF or locale cookie before anyone signs in fills the jar
+without establishing a session. Anything needing to know whether a sign-in
+happened has to track the sign-in itself.
+
+The browser side has the same requirement. `ScenarioBrowserProvider.reset`
+discards every actor's per-scenario state — cookies, storage, open pages — while
+keeping the browser, and is called between scenarios so one scenario cannot
+leave the next signed in as somebody else.
+
+**What this rules out:** hoisting the jar to a module-level or per-service map,
+sharing one jar across actors, reading `Set-Cookie` only from the sign-in
+response, treating `empty === false` as "signed in", or skipping `reset` between
+scenarios as an optimisation.

package/knowledge/decisions/security/workflow-scenario-steps-are-never-network-invocable.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: A scenario step is never registered as a callable RPC and never dispatched on the queue
+description: A step drives a browser and holds an actor's session, so exposing it as an RPC would put that reach on the network
+tags: workflow
+---
+
+# A scenario step is never registered as a callable RPC and never dispatched on the queue
+
+`ScenarioStepMeta` in `dsl/workflow-dsl.types.ts` is a distinct meta type from
+`RpcStepMeta` on purpose. A scenario step runs locally through `runPikkuFunc`
+and must never be treated as dispatchable on the queue or replay path, nor
+registered as a callable RPC — a browser-driving step must not be
+network-invocable. It executes with a browser handle and an actor's
+authenticated session in hand; exposed as an RPC it would hand a remote caller
+that reach.
+
+`PikkuScenarioService.scenarioStep` reflects this at runtime: it always runs
+through `engine.inlineStep` with `runPikkuFunc`, never through `rpcStep`, so no
+transport is involved. A step declaring `browser: true` is refused outright
+unless both a browser provider is registered and an actor was supplied, with an
+error saying which is missing.
+
+Scenario steps are also modelled as sessionless pikku functions (see
+`scenario-step.test.ts`) because a step is driven by an actor, not by a wire
+session.
+
+**What this rules out:** collapsing `ScenarioStepMeta` into `RpcStepMeta`,
+registering step functions in the RPC map so they "can be tested directly",
+routing a scenario step through `rpcStep`/`dispatchStep`, or defaulting a
+`browser: true` step to run without an actor.

package/knowledge/index.md

@@ -0,0 +1,24 @@
+---
+type: overview
+title: Knowledge
+description: Why @pikku/core is built the way it is — the reasoning that used to live in comments
+---
+
+# Knowledge
+
+Pikku's source says *what* it does. These notes say *why*, for the handful of
+choices where the code alone reads as arbitrary or, worse, reads as a mistake.
+
+The rule that produced this directory: **reasoning never lives in code.** A
+comment that restates the line below it is deleted. A comment that records a
+decision — a constraint, a trade-off, a thing that was tried and failed — moves
+here and gets a name, so it can be linked to and argued with.
+
+Everything mechanical is generated or inspectable: the wirings, the schemas, the
+meta files, the export surface. A note that repeats them is a copy that will
+drift.
+
+<!-- pikku:knowledge-index -->
+- [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
+- [questions](questions/index.md) — something asked and not yet answered
+<!-- /pikku:knowledge-index -->

package/knowledge/questions/index.md

@@ -0,0 +1,15 @@
+---
+type: overview
+title: Questions
+description: Things asked of core and not yet answered
+---
+
+# Questions
+
+Something asked and not yet answered. A question earns a note when the code
+currently makes a choice that nobody has defended — the choice stays, the doubt
+gets recorded.
+
+<!-- pikku:knowledge-index -->
+_Nothing here yet._
+<!-- /pikku:knowledge-index -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.72",
+  "version": "0.12.77",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -8,7 +8,7 @@
   "main": "dist/index.js",
   "type": "module",
   "scripts": {
-    "tsc": "tsc",
+    "tsc": "tsc && tsc -p tsconfig.type-tests.json",
     "build": "tsc -b",
     "ncu": "npx npm-check-updates",
     "release": "npm run build && npm test",
@@ -27,6 +27,7 @@
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
     "./actor-flow": "./dist/wirings/actor-flow/index.js",
+    "./virtual-user": "./dist/wirings/virtual-user/index.js",
     "./channel/local": "./dist/wirings/channel/local/index.js",
     "./channel/serverless": "./dist/wirings/channel/serverless/index.js",
     "./http": "./dist/wirings/http/index.js",
@@ -45,6 +46,8 @@
     "./node": "./dist/wirings/node/index.js",
     "./credential": "./dist/wirings/credential/index.js",
     "./scope": "./dist/wirings/scope/index.js",
+    "./role": "./dist/wirings/role/index.js",
+    "./persona": "./dist/wirings/persona/index.js",
     "./secret": "./dist/wirings/secret/index.js",
     "./variable": "./dist/wirings/variable/index.js",
     "./oauth2": "./dist/wirings/oauth2/index.js",
@@ -54,6 +57,7 @@
     "./services/v8-coverage": "./dist/services/v8-coverage-service.js",
     "./services/istanbul-coverage": "./dist/services/istanbul-coverage-service.js",
     "./services/local-content": "./dist/services/local-content.js",
+    "./services/local-content-request-handler": "./dist/services/local-content-request-handler.js",
     "./services/temporary-file-service": "./dist/services/temporary-file-service.js",
     "./crypto-utils": "./dist/crypto-utils.js",
     "./hmac": "./dist/utils/hmac.js",

package/src/column-form.test.ts

@@ -0,0 +1,97 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  hashToken,
+  unsafeAsHashed,
+  unsafeAsSealed,
+  unsafeAsWrapped,
+} from './column-form.js'
+import type {
+  HashedValue,
+  SealedValue,
+  WrappedValue,
+} from './data-classification.js'
+import { deriveKEK, envelopeEncrypt, envelopeRewrap } from './crypto-utils.js'
+
+const KEY_MATERIAL = 'x'.repeat(32)
+
+describe('hashToken', () => {
+  test('is the sha256 of the input, lowercase hex', async () => {
+    // Known vector, so a refactor of the hex encoding cannot quietly change
+    // what every stored hash in every downstream database means.
+    assert.equal(
+      await hashToken('abc'),
+      'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
+    )
+  })
+
+  test('is stable across calls', async () => {
+    assert.equal(await hashToken('token'), await hashToken('token'))
+  })
+
+  test('separates different inputs', async () => {
+    assert.notEqual(await hashToken('a'), await hashToken('b'))
+  })
+})
+
+describe('the form brands', () => {
+  test('a plain string is not assignable to any of them', () => {
+    // @ts-expect-error plaintext cannot be written to a wrapped column
+    const wrapped: WrappedValue = 'not-ciphertext'
+    // @ts-expect-error plaintext cannot be written to a sealed column
+    const sealed: SealedValue = 'not-ciphertext'
+    // @ts-expect-error a raw token cannot be written where its hash belongs
+    const hashed: HashedValue = 'raw-token'
+    assert.ok(wrapped && sealed && hashed)
+  })
+
+  test('the three do not substitute for one another', () => {
+    const wrapped = unsafeAsWrapped('ct')
+    // @ts-expect-error a value fabric cannot read is not one it can
+    const asWrapped: WrappedValue = unsafeAsSealed('ct')
+    // @ts-expect-error a digest is not ciphertext
+    const asHashed: HashedValue = wrapped
+    assert.ok(asWrapped && asHashed)
+  })
+
+  test('but each still widens to string, so reads and query operands are unaffected', () => {
+    const asString: string = unsafeAsWrapped('ct')
+    assert.equal(asString, 'ct')
+    assert.equal(`${unsafeAsHashed('abc')}`, 'abc')
+  })
+})
+
+describe('the envelope primitives produce the brand', () => {
+  test('envelopeEncrypt returns ciphertext that is writable to a wrapped column', async () => {
+    const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
+    // No cast: this is the whole mechanism — the only way to satisfy the
+    // column type is to have actually encrypted something.
+    const forColumn: WrappedValue = ciphertext
+    const dekForColumn: WrappedValue = wrappedDEK
+    assert.ok(forColumn.length > 0 && dekForColumn.length > 0)
+  })
+
+  test('a rewrapped DEK is still writable, so rotation needs no escape hatch', async () => {
+    const oldKek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
+    const newKek = await deriveKEK('y'.repeat(32), 'c2FsdA')
+    const { wrappedDEK } = await envelopeEncrypt(oldKek, 'value')
+    const rewrapped: WrappedValue = await envelopeRewrap(
+      oldKek,
+      newKek,
+      wrappedDEK
+    )
+    assert.notEqual(rewrapped, wrappedDEK)
+  })
+
+  test('decrypting accepts a bare string, so reading a row back needs no cast', async () => {
+    const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
+    const { envelopeDecrypt } = await import('./crypto-utils.js')
+    const fromRow: string = ciphertext
+    assert.equal(
+      await envelopeDecrypt<string>(kek, fromRow, wrappedDEK),
+      'value'
+    )
+  })
+})

package/src/column-form.ts

@@ -0,0 +1,58 @@
+// knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
+import type {
+  HashedValue,
+  SealedValue,
+  WrappedValue,
+} from './data-classification.js'
+
+/**
+ * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
+ *
+ * Deliberately unpeppered. These are high-entropy random bearer tokens, not
+ * passwords: there is no candidate set to search, so a pepper would add a key
+ * to manage and a rotation story to own while buying nothing. A column holding
+ * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
+ * a different type entirely.
+ *
+ * Async because it runs on WebCrypto rather than `node:crypto`, so the same
+ * code path works in a Worker. Callers that hash a bearer token on every
+ * request are already async.
+ */
+export const hashToken = async (raw: string): Promise<HashedValue> => {
+  const subtle = globalThis.crypto?.subtle
+  if (!subtle) {
+    throw new Error('WebCrypto not available')
+  }
+  const digest = await subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(raw)
+  )
+  let hex = ''
+  for (const byte of new Uint8Array(digest)) {
+    hex += byte.toString(16).padStart(2, '0')
+  }
+  return hex as HashedValue
+}
+
+/**
+ * Assert that a string already in storage is ciphertext of the given form.
+ *
+ * The brands exist so that new writes must come from a real encrypt/hash call,
+ * but three paths legitimately hold such a value as a bare `string`: a
+ * migration backfilling rows written before the column declared its form, a
+ * test fixture, and a value arriving over the wire from a service that sealed
+ * it elsewhere. Each of those is a promise the caller is making, not something
+ * the type system can check — which is why these are named to be greppable and
+ * why there is no non-`unsafe` spelling. If one of these appears in ordinary
+ * request-handling code, that is the bug.
+ */
+export const unsafeAsWrapped = (stored: string): WrappedValue =>
+  stored as WrappedValue
+
+/** See `unsafeAsWrapped`. */
+export const unsafeAsSealed = (stored: string): SealedValue =>
+  stored as SealedValue
+
+/** See `unsafeAsWrapped`. */
+export const unsafeAsHashed = (stored: string): HashedValue =>
+  stored as HashedValue