@pikku/core 0.12.72 → 0.12.74

package/src/permissions.ts

@@ -10,23 +10,6 @@ import type {
 import { pikkuState } from './pikku-state.js'
 import { ForbiddenError } from './errors/errors.js'
 
-/**
- * Evaluates a single permission group. A group ORs its branches together and
- * ANDs the entries within a branch: the group passes if at least one branch
- * (an array of permission functions, all of which must return true — or a lone
- * function) is satisfied.
- *
- * This is the only place OR lives in authorization. Everything cross-cutting —
- * global permissions, scopes, and auth — ANDs together; a function's own
- * `permissions` group is the sole place where "owner OR admin"-style
- * alternatives are expressed.
- *
- * @param permissions - The permission group to evaluate.
- * @param services - The core services required for permission validation.
- * @param data - The request data passed to each permission function.
- * @param wire - The wire object containing request/response context and session.
- * @returns A promise resolving to true if the group is satisfied.
- */
 const verifyPermissions = async (
   permissions: CorePermissionGroup,
   services: CoreServices,
@@ -71,20 +54,6 @@ export const clearPermissionsCache = () => {
   }
 }
 
-/**
- * Registers wire-agnostic global permissions. Global permissions are an AND
- * gate: every registered requirement must pass on every function invocation,
- * regardless of transport. A requirement may be a single permission function
- * or a permission group (in which case that group ORs internally, but the
- * group as a whole must still pass).
- *
- * Global permissions never satisfy a function's own `permissions` — the two
- * are independent gates that both have to pass, so a broad global can only
- * ever narrow access.
- *
- * @example
- * addGlobalPermission([signedInUser])
- */
 export const addGlobalPermission = (
   permissions: CorePermissionGroup | CorePikkuPermission[],
   packageName: string | null = null
@@ -120,11 +89,27 @@ export const addTagPermission = (
   )
 }
 
+const bucket = (
+  packageName: string | null
+): (CorePermissionGroup | CorePikkuPermission)[] =>
+  (pikkuState(packageName, 'permissions', 'global') as unknown as (
+    | CorePermissionGroup
+    | CorePikkuPermission
+  )[]) ?? []
+
 /**
- * Resolves the registered global permission requirements for a package,
- * caching the resolved array per package. The cache is keyed by package name
- * (an empty string for the root package) so packages never collide, and it is
- * cleared whenever globals are registered or on hot reload.
+ * Global permissions in effect for a function, root ones first.
+ *
+ * A function that belongs to a package reads *both* buckets, not just its own.
+ * The generated `addGlobalPermission` wrapper always registers under the root
+ * (`null`) package — it takes no package argument — so resolving the package
+ * bucket alone meant an application's "every request needs a signed-in user"
+ * rule silently stopped at the addon boundary, and the bucket the addon's
+ * functions did read was one no host could write to. Both directions of that
+ * are wrong, and the safe union is to apply everything: globals are an AND
+ * gate, so adding the root ones can only ever tighten.
+ *
+ * knowledge: decisions/security/global-permissions-and-function-permissions-are-independent-gates.md
  */
 const resolveGlobalPermissions = (
   packageName: string | null
@@ -134,12 +119,9 @@ const resolveGlobalPermissions = (
   if (cached) {
     return cached
   }
-  const globals = pikkuState(
-    packageName,
-    'permissions',
-    'global'
-  ) as unknown as (CorePermissionGroup | CorePikkuPermission)[]
-  const resolved = globals && globals.length > 0 ? [...globals] : []
+  const resolved = packageName
+    ? [...bucket(null), ...bucket(packageName)]
+    : [...bucket(null)]
   globalPermissionsCache[key] = resolved
   return resolved
 }
@@ -149,17 +131,6 @@ const asGroup = (
 ): CorePermissionGroup =>
   typeof entry === 'function' ? { permission: entry } : entry
 
-/**
- * Runs authorization for a function invocation. Two independent gates, both of
- * which must pass:
- *
- * 1. Global permissions — AND. Every registered global requirement must pass.
- * 2. Function permissions — OR. The function's own `permissions` group must be
- *    satisfied (see {@link verifyPermissions}).
- *
- * A passing global requirement never contributes to the function gate, so a
- * broad global like `signedIn` can't satisfy an admin-only function.
- */
 export const runPermissions = async ({
   funcPermissions,
   services,
@@ -197,25 +168,8 @@ export const runPermissions = async ({
   }
 }
 
-/**
- * Checks whether a session passes the auth checks (pikkuAuth only) for a
- * given function/agent. Skips pikkuPermission checks since those require
- * request data which isn't available at filter time. Global auth requirements
- * are included so a filtered list honours app-wide auth.
- *
- * `funcPermissions` is the live {@link CorePermissionGroup} 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 those metadata entries
- * would resolve against is never populated. Passing metadata here would silently
- * collect nothing and let every gated tool through.
- *
- * @param funcPermissions - The live permission group from the func/agent config
- * @param session - The user's session
- * @param services - Singleton services
- * @param packageName - Optional package namespace
- * @returns true if the session passes the auth checks (or no auth checks exist)
- */
 export const checkAuthPermissions = async (
+  /** Must be the live permission group from the func/agent config, never metadata. */
   funcPermissions: CorePermissionGroup | undefined,
   session: CoreUserSession,
   services: CoreServices,
@@ -230,9 +184,6 @@ export const checkAuthPermissions = async (
     never
   >
 
-  // Collect auth-only (pikkuAuth) predicates from globals and the function's
-  // referenced permissions. Data-dependent permissions are ignored — they
-  // can't be evaluated without request data at filter time.
   const authPerms: CorePikkuPermission<any, any, any>[] = []
 
   const collect = (perm: CorePermissionGroup | CorePikkuPermission) => {
@@ -260,7 +211,6 @@ export const checkAuthPermissions = async (
     collect(funcPermissions)
   }
 
-  // No auth permissions = allowed (only data-dependent permissions exist)
   if (authPerms.length === 0) return true
 
   for (const perm of authPerms) {

package/src/pikku-request.ts

@@ -1,6 +1,4 @@
 /**
- * Simplest class to represent a pikku request.
- * @template In - The type of the request body.
  * @group RequestResponse
  */
 export abstract class PikkuRequest<In = any> {
@@ -10,10 +8,6 @@ export abstract class PikkuRequest<In = any> {
     this.#data = data
   }
 
-  /**
-   * Retrieves the data
-   * @returns A promise that resolves to an object containing the combined data.
-   */
   public async data(): Promise<In> {
     if (this.#data === undefined) {
       throw new Error('Data not found')

package/src/pikku-state.ts

@@ -14,7 +14,7 @@ import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
 import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
 import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
-const PIKKU_STATE_KEY = Symbol('@pikku/core/state')
+const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
 
 export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
   if (!(globalThis as any)[PIKKU_STATE_KEY]) {
@@ -23,22 +23,6 @@ export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
   return (globalThis as any)[PIKKU_STATE_KEY] as Map<string, PikkuPackageState>
 }
 
-/**
- * Get or set package-scoped pikku state
- *
- * @param packageName - Package name (null for main package, '@scope/package' for addon packages)
- * @param type - State category (function, rpc, http, etc.)
- * @param content - Content key within the category
- * @param value - Optional value to set
- * @returns The current value of the state
- *
- * @example
- * // Main package
- * pikkuState(null, 'function', 'functions').get(funcName)
- *
- * // Addon package
- * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
- */
 export const pikkuState = <
   Type extends keyof PikkuPackageState,
   Content extends keyof PikkuPackageState[Type],
@@ -50,7 +34,6 @@ export const pikkuState = <
 ): PikkuPackageState[Type][Content] => {
   const resolvedPackageName = packageName ?? '__main__'
 
-  // Initialize package state if it doesn't exist
   if (!getAllPackageStates().has(resolvedPackageName)) {
     initializePikkuState(resolvedPackageName)
   }
@@ -160,9 +143,6 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
 })
 
-/**
- * Initialize state for a new package
- */
 export const initializePikkuState = (packageName: string): void => {
   if (!getAllPackageStates().has(packageName)) {
     getAllPackageStates().set(packageName, createEmptyPackageState())
@@ -170,13 +150,12 @@ export const initializePikkuState = (packageName: string): void => {
 }
 
 export const resetPikkuState = () => {
-  // Preserve the errors map before resetting
+  // Error definitions come from module-import side effects that never re-run.
   const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
 
   ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
   initializePikkuState('__main__')
 
-  // Restore the errors map if it existed
   if (existingErrors) {
     const mainState = getAllPackageStates().get('__main__')!
     mainState.misc.errors = existingErrors
@@ -201,13 +180,6 @@ export const getCreateWireServices = (): CreateWireServices | undefined => {
   return pikkuState(null, 'package', 'factories')?.createWireServices
 }
 
-/**
- * Register service factories for an addon package.
- * These factories are used to create services when the package's functions are invoked.
- *
- * @param packageName - The package name (e.g., '@pikku/templates-function-addon')
- * @param factories - The service factory functions
- */
 export const addPackageServiceFactories = (
   packageName: string,
   factories: NonNullable<PikkuPackageState['package']['factories']>

package/src/production-barrels-stay-lean.test.ts

@@ -0,0 +1,110 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, resolve, relative } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Statements that only move types. TypeScript erases them, so they cost a
+ * production bundle nothing and are deliberately not followed.
+ */
+const TYPE_ONLY = /^\s*(?:import|export)\s+type\b/
+
+/**
+ * The modules a production server must never load by importing a barrel.
+ *
+ * Each is scenario or virtual-user runtime: `http-personas` signs personas in
+ * and reaches the actor-flow conversation runner, which reaches the agent
+ * runner. None of it runs in production, and an unbundled Node or Lambda deploy
+ * does no tree-shaking — it loads whatever the graph names.
+ */
+const FORBIDDEN = [
+  'services/http-personas.ts',
+  'wirings/actor-flow/run-conversation.ts',
+  'wirings/workflow/pikku-scenario-service.ts',
+]
+
+const resolveSpecifier = (fromFile: string, specifier: string) => {
+  const base = resolve(dirname(fromFile), specifier.replace(/\.js$/, ''))
+  for (const candidate of [`${base}.ts`, join(base, 'index.ts')]) {
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Every module loaded as a side effect of importing `entry`, following value
+ * imports only.
+ *
+ * A dynamic `await import(...)` is not followed: it does not run at module
+ * init, which is the whole reason `pikku-scenario-service` reaches
+ * `http-personas` that way.
+ */
+const runtimeGraph = (entry: string): Set<string> => {
+  const seen = new Set<string>()
+  const queue = [entry]
+
+  while (queue.length) {
+    const file = queue.pop()!
+    if (seen.has(file)) continue
+    seen.add(file)
+
+    for (const line of readFileSync(file, 'utf-8').split('\n')) {
+      if (TYPE_ONLY.test(line)) continue
+      const specifier = line.match(/\bfrom\s+'(\.[^']+)'/)?.[1]
+      if (!specifier) continue
+      const target = resolveSpecifier(file, specifier)
+      if (target) queue.push(target)
+    }
+  }
+
+  return seen
+}
+
+describe('production barrels stay lean', () => {
+  for (const barrel of ['services/index.ts', 'wirings/workflow/index.ts']) {
+    test(`@pikku/core ${barrel} does not load scenario runtime`, () => {
+      const reached = runtimeGraph(join(srcRoot, barrel))
+      const offenders = FORBIDDEN.filter((module) =>
+        reached.has(join(srcRoot, module))
+      )
+
+      assert.deepEqual(
+        offenders,
+        [],
+        `${barrel} pulls scenario runtime into every app that imports it:\n` +
+          `${offenders.join('\n')}\n` +
+          `Export the value from '@pikku/core/persona' instead — types may stay here.`
+      )
+    })
+  }
+
+  test('the persona entry point still exports the runtime that moved', async () => {
+    const persona = await import('./wirings/persona/index.js')
+
+    for (const name of [
+      'createHttpPersonas',
+      'HttpPersona',
+      'postScenarioJson',
+      'readScenarioHttpResponse',
+    ]) {
+      assert.ok(
+        name in persona,
+        `@pikku/core/persona no longer exports ${name}; it has to live somewhere`
+      )
+    }
+  })
+
+  test('the graph walker actually reaches things', () => {
+    // Guards the test above: a walker that silently resolved nothing would pass
+    // no matter what the barrels imported.
+    const reached = runtimeGraph(join(srcRoot, 'wirings/persona/index.ts'))
+    assert.ok(
+      reached.has(join(srcRoot, 'services/http-personas.ts')),
+      `walker failed to reach a known value import; reached ${reached.size} files:\n` +
+        [...reached].map((f) => relative(srcRoot, f)).join('\n')
+    )
+  })
+})

package/src/remote.test.ts

@@ -0,0 +1,172 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { buildRemoteHeaders } from './remote.js'
+import { pikkuRemoteAuthMiddleware } from './middleware/remote-auth.js'
+import { resetPikkuState } from './pikku-state.js'
+import { WeakKeyMaterialError } from './errors/errors.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const STRONG_SECRET = 'a'.repeat(43)
+const WEAK_SECRET = 'dev-remote-secret'
+
+const createSecrets = (secret: string) => ({
+  getSecret: async (key: string) => {
+    if (key === 'PIKKU_REMOTE_SECRET') return secret
+    throw new Error(`Secret ${key} not found`)
+  },
+})
+
+/**
+ * Signing is deliberately free here so the measurement isolates key derivation.
+ */
+const createJWT = () => ({
+  encode: async (_expiresIn: unknown, payload: unknown) =>
+    Buffer.from(JSON.stringify(payload)).toString('base64url'),
+  decode: async (token: string) =>
+    JSON.parse(Buffer.from(token, 'base64url').toString('utf-8')),
+})
+
+const createRequest = (
+  headers: Record<string, string>,
+  path = '/remote/rpc/myFunc'
+) => ({
+  header: (name: string) => headers[name.toLowerCase()] || headers[name],
+  path: () => path,
+  method: () => 'POST',
+})
+
+const roundTrip = async (secret: string, session: unknown) => {
+  const jwt = createJWT()
+  const secrets = createSecrets(secret)
+
+  const headers = await buildRemoteHeaders(
+    jwt as any,
+    secrets as any,
+    'myFunc',
+    session
+  )
+
+  let received: unknown
+  await pikkuRemoteAuthMiddleware(
+    { secrets, jwt } as any,
+    {
+      http: {
+        request: createRequest({ authorization: headers.authorization! }),
+      },
+      setSession: async (s: unknown) => {
+        received = s
+      },
+    } as any,
+    async () => {}
+  )
+  return received
+}
+
+describe('remote RPC session round trip', () => {
+  test('round-trips the session through header build and middleware verify', async () => {
+    const session = { userId: 'user-1', role: 'admin' }
+    assert.deepStrictEqual(await roundTrip(STRONG_SECRET, session), session)
+  })
+
+  test('a header built with one secret is rejected by a peer holding another', async () => {
+    const jwt = createJWT()
+    const headers = await buildRemoteHeaders(
+      jwt as any,
+      createSecrets(STRONG_SECRET) as any,
+      'myFunc',
+      { userId: 'user-1' }
+    )
+
+    await assert.rejects(() =>
+      pikkuRemoteAuthMiddleware(
+        { secrets: createSecrets('b'.repeat(43)), jwt } as any,
+        {
+          http: {
+            request: createRequest({ authorization: headers.authorization! }),
+          },
+          setSession: async () => {},
+        } as any,
+        async () => {}
+      )
+    )
+  })
+
+  test('a full round trip stays under the per-hop latency budget', async () => {
+    const session = { userId: 'user-1', role: 'admin' }
+
+    // Warm up so the measurement excludes module/JIT startup.
+    await roundTrip(STRONG_SECRET, session)
+
+    const iterations = 5
+    const start = performance.now()
+    for (let i = 0; i < iterations; i++) {
+      await roundTrip(STRONG_SECRET, session)
+    }
+    const perRoundTrip = (performance.now() - start) / iterations
+
+    assert.ok(
+      perRoundTrip < 20,
+      `remote RPC round trip took ${perRoundTrip.toFixed(1)}ms, budget is 20ms`
+    )
+  })
+})
+
+describe('PIKKU_REMOTE_SECRET strength', () => {
+  test('buildRemoteHeaders rejects a secret shorter than 32 characters', async () => {
+    await assert.rejects(
+      () =>
+        buildRemoteHeaders(
+          createJWT() as any,
+          createSecrets(WEAK_SECRET) as any,
+          'myFunc',
+          { userId: 'user-1' }
+        ),
+      (err: unknown) => err instanceof WeakKeyMaterialError
+    )
+  })
+
+  test('buildRemoteHeaders rejects a weak secret even with no session to encrypt', async () => {
+    await assert.rejects(
+      () =>
+        buildRemoteHeaders(
+          createJWT() as any,
+          createSecrets(WEAK_SECRET) as any,
+          'myFunc'
+        ),
+      (err: unknown) => err instanceof WeakKeyMaterialError
+    )
+  })
+
+  test('the middleware rejects a weak secret rather than authenticating with it', async () => {
+    const jwt = createJWT()
+    const headers = await buildRemoteHeaders(
+      jwt as any,
+      createSecrets(STRONG_SECRET) as any,
+      'myFunc',
+      { userId: 'user-1' }
+    )
+
+    await assert.rejects(
+      () =>
+        pikkuRemoteAuthMiddleware(
+          { secrets: createSecrets(WEAK_SECRET), jwt } as any,
+          {
+            http: {
+              request: createRequest({ authorization: headers.authorization! }),
+            },
+            setSession: async () => {},
+          } as any,
+          async () => {}
+        ),
+      (err: unknown) => err instanceof WeakKeyMaterialError
+    )
+  })
+
+  test('a secret of exactly 32 characters is accepted', async () => {
+    const session = { userId: 'user-1' }
+    assert.deepStrictEqual(await roundTrip('x'.repeat(32), session), session)
+  })
+})

package/src/remote.ts

@@ -1,13 +1,15 @@
 import type { JWTService } from './services/jwt-service.js'
 import type { SecretService } from './services/secret-service.js'
-import { encryptJSON } from './crypto-utils.js'
+import {
+  assertStrongKeyMaterial,
+  encryptWithKeyMaterial,
+  REMOTE_SESSION_INFO,
+} from './crypto-utils.js'
 
 /**
- * Build Authorization headers with JWT-signed session and traceId for
- * pikkuRemoteAuthMiddleware on the receiving end.
- *
- * Used by all deployment services (Kysely, Redis, MongoDB, Lambda, CF, Azure)
- * regardless of transport (HTTP, Lambda Invoke, service bindings).
+ * Authorization headers carrying a JWT-signed session and traceId for
+ * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
+ * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
 export async function buildRemoteHeaders(
   jwt: JWTService | undefined,
@@ -27,8 +29,16 @@ export async function buildRemoteHeaders(
   } catch {}
 
   if (secret && jwt) {
+    assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret)
     const sessionEnc = session
-      ? await encryptJSON(secret, { session })
+      ? await encryptWithKeyMaterial(
+          'PIKKU_REMOTE_SECRET',
+          secret,
+          REMOTE_SESSION_INFO,
+          {
+            session,
+          }
+        )
       : undefined
     const token = await jwt.encode(
       { value: 5, unit: 'minute' },

package/src/schema.ts

@@ -9,13 +9,6 @@ import { pikkuState, getAllPackageStates } from './pikku-state.js'
 const schemaKey = (name: string, packageName: string | null): string =>
   packageName ? `${packageName}:${name}` : name
 
-/**
- * Adds a schema to the schemas map for a specific package.
- * @param name - The name of the schema.
- * @param value - The schema value.
- * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
- * @ignore
- */
 export const addSchema = (
   name: string,
   value: any,
@@ -25,13 +18,6 @@ export const addSchema = (
   pikkuState(packageName, 'misc', 'schemas').set(name, schema)
 }
 
-/**
- * Retrieves a schema from the schemas map for a specific package.
- * @param name - The name of the schema.
- * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
- * @returns The schema value or undefined if not found.
- * @ignore
- */
 export const getSchema = (
   name: string,
   packageName: string | null = null
@@ -39,10 +25,6 @@ export const getSchema = (
   return pikkuState(packageName, 'misc', 'schemas').get(name)
 }
 
-/**
- * Loads a schema and compiles it into a validator.
- * @param logger - A logger for logging information.
- */
 export const compileAllSchemas = (
   logger: Logger,
   schemaService?: SchemaService
@@ -95,27 +77,11 @@ const validateAllSchemasLoaded = (
 }
 
 /**
- * Fill in absent top-level properties from their schema `default`.
- *
- * A `default` reaches the generated JSON Schema and keeps the property out of
- * `required`, so omitting it validates — but nothing was ever filling it in.
- * JSON Schema validators are pure by specification and none of the ones Pikku
- * ships with (`@cfworker/json-schema`, and Ajv unless `useDefaults` is set)
- * annotate the instance, so the function received `undefined` for a property
- * its generated type declares as present. That is the worst shape a mismatch
- * can take: validation permits the omission, the type says the value is there,
- * and the body reads `undefined`.
- *
- * Applied unconditionally rather than alongside `coerceTopLevelDataFromSchema`,
- * whose `coerceDataFromSchema` flag is about decoding transport-encoded values
- * (a query string's `"1,2"` into an array). Defaults are a property of the
- * schema, not of how the call arrived, so gating them on that flag would apply
- * them over HTTP and skip them on a direct RPC invocation.
- *
- * Returns the data to use, which is a new object only when defaults had to be
- * added to a nullish input — a call made with no arguments at all still gets
- * them. Values are cloned so an object or array default (`[]`, `{}`) is never
- * shared as one mutable instance across every request.
+ * Fills in absent top-level properties from their schema `default`. Applied
+ * unconditionally: a default belongs to the schema, not to the transport the
+ * call arrived on, and runs before coercion so a defaulted and a supplied
+ * value are treated identically from here on. Values are cloned so an object
+ * or array default is never shared as one mutable instance across requests.
  */
 export const applyDefaultsFromSchema = (
   schemaName: string,