@pikku/core 0.12.72 → 0.12.77

package/src/middleware/remote-auth.test.ts

@@ -3,18 +3,19 @@ import assert from 'node:assert'
 import { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 import { UnauthorizedError } from '../errors/errors.js'
 import { resetPikkuState } from '../pikku-state.js'
-import { encryptJSON } from '../crypto-utils.js'
+import { encryptWithKeyMaterial, REMOTE_SESSION_INFO } from '../crypto-utils.js'
+import { createSecretValue } from '../secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
-const TEST_SECRET = 'test-remote-secret-key'
+const TEST_SECRET = 'test-remote-secret-key-with-enough-entropy'
 
 const createMockSecrets = (secret?: string) => ({
   getSecret: async (key: string) => {
     if (key === 'PIKKU_REMOTE_SECRET' && secret !== undefined) {
-      return secret
+      return createSecretValue(secret)
     }
     throw new Error(`Secret ${key} not found`)
   },
@@ -354,9 +355,14 @@ describe('pikkuRemoteAuthMiddleware', () => {
   describe('session decryption', () => {
     test('should decrypt and set session when payload.session exists', async () => {
       const sessionData = { userId: 'user-1', role: 'admin' }
-      const encryptedSession = await encryptJSON(TEST_SECRET, {
-        session: sessionData,
-      })
+      const encryptedSession = await encryptWithKeyMaterial(
+        'PIKKU_REMOTE_SECRET',
+        TEST_SECRET,
+        REMOTE_SESSION_INFO,
+        {
+          session: sessionData,
+        }
+      )
       let receivedSession: any
 
       await pikkuRemoteAuthMiddleware(
@@ -407,9 +413,14 @@ describe('pikkuRemoteAuthMiddleware', () => {
     })
 
     test('should skip setSession when setSession is not available', async () => {
-      const encryptedSession = await encryptJSON(TEST_SECRET, {
-        session: { userId: 'u1' },
-      })
+      const encryptedSession = await encryptWithKeyMaterial(
+        'PIKKU_REMOTE_SECRET',
+        TEST_SECRET,
+        REMOTE_SESSION_INFO,
+        {
+          session: { userId: 'u1' },
+        }
+      )
       let nextCalled = false
 
       await pikkuRemoteAuthMiddleware(
@@ -434,7 +445,12 @@ describe('pikkuRemoteAuthMiddleware', () => {
     })
 
     test('should skip setSession when decrypted.session is falsy', async () => {
-      const encryptedSession = await encryptJSON(TEST_SECRET, { session: null })
+      const encryptedSession = await encryptWithKeyMaterial(
+        'PIKKU_REMOTE_SECRET',
+        TEST_SECRET,
+        REMOTE_SESSION_INFO,
+        { session: null }
+      )
       let setSessionCalled = false
 
       await pikkuRemoteAuthMiddleware(

package/src/middleware/remote-auth.ts

@@ -1,6 +1,10 @@
 import { UnauthorizedError } from '../errors/errors.js'
 import { pikkuMiddleware } from '../types/core.types.js'
-import { decryptJSON } from '../crypto-utils.js'
+import {
+  assertStrongKeyMaterial,
+  decryptWithKeyMaterial,
+  REMOTE_SESSION_INFO,
+} from '../crypto-utils.js'
 
 export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
   async ({ secrets, jwt }, { http, setSession }, next) => {
@@ -10,13 +14,15 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
 
     let secret: string
     try {
-      secret = await secrets.getSecret('PIKKU_REMOTE_SECRET')
+      secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal()
     } catch {
       if (http.request.path().startsWith('/remote/rpc/')) {
         throw new UnauthorizedError()
       }
       return next()
     }
+    assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret)
+
     if (!jwt) {
       throw new Error('PIKKU_REMOTE_SECRET set but JWT service missing')
     }
@@ -56,8 +62,10 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
 
     if (payload?.session) {
       try {
-        const decrypted = await decryptJSON<{ session?: unknown }>(
+        const decrypted = await decryptWithKeyMaterial<{ session?: unknown }>(
+          'PIKKU_REMOTE_SECRET',
           secret,
+          REMOTE_SESSION_INFO,
           payload.session
         )
         if (decrypted?.session && setSession) {

package/src/middleware/telemetry.ts

@@ -1,21 +1,6 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
-/**
- * Outer telemetry middleware that captures total request duration and outcome.
- * Runs at `highest` priority (outermost in the middleware chain).
- *
- * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
- * - Total duration (including all middleware)
- * - Outcome (ok/error)
- * - Wire metadata (wireType, wireId, traceId)
- * - HTTP details (method, path, status) if applicable
- *
- * @example
- * ```typescript
- * import { telemetryOuter } from '@pikku/core/middleware'
- * addTagMiddleware('myTag', [telemetryOuter()])
- * ```
- */
+/** Outermost telemetry: total duration, including every middleware. */
 export const telemetryOuter = pikkuMiddlewareFactory<{
   environmentId?: string
   orgId?: string
@@ -58,21 +43,7 @@ export const telemetryOuter = pikkuMiddlewareFactory<{
   })
 })
 
-/**
- * Inner telemetry middleware that captures function execution duration and user context.
- * Runs at `lowest` priority (innermost, closest to the function).
- *
- * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
- * - Function-only duration (excluding outer middleware like auth)
- * - User identity (pikkuUserId) if authenticated
- * - Wire metadata (wireType, wireId, traceId)
- *
- * @example
- * ```typescript
- * import { telemetryInner } from '@pikku/core/middleware'
- * addTagMiddleware('myTag', [telemetryInner()])
- * ```
- */
+/** Innermost telemetry: function-only duration, excluding outer middleware. */
 export const telemetryInner = pikkuMiddlewareFactory<{
   environmentId?: string
   orgId?: string

package/src/middleware-runner.test.ts

@@ -114,7 +114,6 @@ describe('combineMiddleware', () => {
   })
 
   test('should execute middleware in correct order: wireInheritedMiddleware (tags) → wireMiddleware → funcInheritedMiddleware (tags) → funcMiddleware', () => {
-    // Setup tagged middleware
     const wiringTagMiddleware: CorePikkuMiddleware = async (
       services,
       wire,
@@ -441,7 +440,6 @@ describe('runMiddleware', () => {
       }
     )
 
-    // Should only execute each middleware once
     assert.deepEqual(executionOrder, ['middleware1', 'middleware2', 'main'])
   })
 

package/src/middleware-runner.ts

@@ -31,23 +31,6 @@ const sortByPriority = (
   )
 }
 
-/**
- * Runs a chain of middleware functions in sequence before executing the main function.
- *
- * @param services - An object containing services (e.g., singletonServices, userSession, etc.)
- * @param wire - The wire context, e.g., { http }.
- * @param middlewares - An array of middleware functions to run.
- * @param main - The main function to execute after all middleware have run.
- * @returns A promise resolving to the result of the main function.
- *
- * @example
- * runMiddleware(
- *   { ...services, userSession },
- *   { http },
- *   [middleware1, middleware2, middleware3],
- *   async () => { return await runMain(); }
- * );
- */
 export const runMiddleware = async <
   Middleware extends CorePikkuMiddleware<any, any>,
 >(
@@ -56,7 +39,6 @@ export const runMiddleware = async <
   middlewares: readonly Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
-  // Sort by priority if not already sorted (cached middleware is pre-sorted)
   const sorted = isSortedByPriority(middlewares)
     ? middlewares
     : ([...middlewares].sort(
@@ -91,14 +73,8 @@ const isSortedByPriority = (
 }
 
 /**
- * Registers tag-scoped middleware. Applies to any wiring (HTTP, Channel,
- * Queue, Scheduler, MCP, CLI, Workflow, Agent) that carries the matching tag.
- *
- * For tree-shaking, wrap in a factory:
- * `export const x = () => addTagMiddleware('tag', [...])`
- *
- * @example
- * export const adminMiddleware = () => addTagMiddleware('admin', [authMiddleware])
+ * Registers tag-scoped middleware for any wiring carrying the tag. Wrap in a
+ * factory (`export const x = () => addTagMiddleware(...)`) for tree-shaking.
  */
 export const addTagMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   tag: string,
@@ -114,14 +90,8 @@ export const addTagMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
 }
 
 /**
- * Registers wire-agnostic global middleware. Runs at the top of every
- * wiring's middleware chain — before wire-, tag-, and function-level
- * entries — across HTTP, Channel, Queue, Scheduler, MCP, CLI, Workflow, Agent.
- *
- * Resolution order: global → wire → tag → function.
- *
- * @example
- * addGlobalMiddleware([telemetryMiddleware])
+ * Registers wire-agnostic global middleware, which runs at the top of every
+ * wiring's chain — before wire-, tag- and function-level entries.
  */
 export const addGlobalMiddleware = <
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -140,17 +110,6 @@ export const addGlobalMiddleware = <
   return middleware
 }
 
-/**
- * Retrieves a registered middleware function by its name.
- *
- * This function looks up middleware that was registered with registerMiddleware.
- * It's used internally by the framework to resolve middleware references in metadata.
- *
- * @param {string} name - The unique name (pikkuFuncId) of the middleware function.
- * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
- *
- * @internal
- */
 const getMiddlewareByName = (name: string): CorePikkuMiddleware | undefined => {
   const middlewareStore = pikkuState(null, 'misc', 'middleware')
   const middleware = middlewareStore[name]
@@ -180,28 +139,6 @@ export const clearMiddlewareCache = () => {
   }
 }
 
-/**
- * Combines wiring-specific middleware with function-level middleware.
- *
- * This function resolves middleware metadata into actual middleware functions and combines them.
- * It filters out wire middleware without tags from inheritedMiddleware to avoid duplication
- * (those are passed separately as wireMiddleware).
- *
- * @param {object} options - Configuration object for combining middleware.
- * @param {MiddlewareMetadata[] | undefined} options.inheritedMiddleware - Metadata from wiring (HTTP + tags + wire with tags).
- * @param {CorePikkuMiddleware[] | undefined} options.wireMiddleware - Inline wire middleware.
- * @param {MiddlewareMetadata[] | undefined} options.funcMiddleware - Function middleware metadata.
- * @returns {CorePikkuMiddleware[]} Combined array of resolved middleware.
- *
- * @example
- * ```typescript
- * const combined = combineMiddleware(wireType, wireId, {
- *   inheritedMiddleware: meta.middleware,
- *   wireMiddleware: [inlineMiddleware],
- *   funcMiddleware: funcMeta.middleware
- * })
- * ```
- */
 export const combineMiddleware = (
   wireType: PikkuWiringTypes,
   uid: string,
@@ -237,7 +174,6 @@ export const combineMiddleware = (
   if (wireInheritedMiddleware) {
     for (const meta of wireInheritedMiddleware) {
       if (meta.type === 'http') {
-        // Look up HTTP middleware group from pikkuState
         const group = pikkuState(packageName, 'middleware', 'httpGroup')[
           meta.route
         ]
@@ -254,7 +190,6 @@ export const combineMiddleware = (
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       } else if (meta.type === 'wire') {
-        // Individual wire middleware (exported, not inline)
         const middleware = getMiddlewareByName(meta.name)
         if (middleware) {
           resolved.push(middleware)
@@ -263,12 +198,11 @@ export const combineMiddleware = (
     }
   }
 
-  // 2. Add inline wire middleware
   if (wireMiddleware) {
     resolved.push(...wireMiddleware)
   }
 
-  // 3. Resolve function inherited middleware (only tags, wire middleware already handled)
+  // Only tags here; wire middleware is resolved via wireInheritedMiddleware.
   if (funcInheritedMiddleware) {
     for (const meta of funcInheritedMiddleware) {
       if (meta.type === 'tag') {
@@ -280,16 +214,13 @@ export const combineMiddleware = (
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       }
-      // Note: wire middleware is already handled in wireInheritedMiddleware
     }
   }
 
-  // 4. Add inline function middleware
   if (funcMiddleware) {
     resolved.push(...funcMiddleware)
   }
 
-  // Sort by priority, deduplicate, and freeze
   sortByPriority(resolved)
   middlewareCache[wireType][uid] = freezeDedupe(
     resolved

package/src/permissions.test.ts

@@ -164,6 +164,36 @@ describe('runPermissions — package isolation', () => {
       message: 'Permission denied',
     })
   })
+
+  test('a root global applies inside a package too', async () => {
+    // The generated `addGlobalPermission` wrapper takes no package argument, so
+    // an application's rules always land in the root bucket. If those stopped
+    // at the addon boundary, "every request needs a signed-in user" would
+    // silently exempt every function an addon contributed.
+    addGlobalPermission([async () => false])
+    await assert.rejects(run({ packageName: 'pkg-a' }), {
+      message: 'Permission denied',
+    })
+  })
+
+  test('root and package globals both have to pass', async () => {
+    addGlobalPermission([async () => true])
+    addGlobalPermission([async () => false], 'pkg-a')
+    await assert.rejects(run({ packageName: 'pkg-a' }), {
+      message: 'Permission denied',
+    })
+  })
+
+  test('passes when the root and package globals both pass', async () => {
+    addGlobalPermission([async () => true])
+    addGlobalPermission([async () => true], 'pkg-a')
+    await run({ packageName: 'pkg-a' })
+  })
+
+  test('a package global does not leak back out to the root', async () => {
+    addGlobalPermission([async () => false], 'pkg-a')
+    await run({})
+  })
 })
 
 describe('checkAuthPermissions', () => {

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']>