@pikku/core 0.12.72 → 0.12.74

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

@@ -95,7 +95,6 @@ describe('authAPIKey middleware', () => {
     const jwtService = {
       encode: async () => 'token',
       decode: async (token: string) => {
-        // Should use header value, not query value
         assert.equal(token, 'header-key')
         return mockUserSession
       },

package/src/middleware/auth-apikey.ts

@@ -1,22 +1,5 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
-/**
- * API key middleware that retrieves a session from the 'x-api-key' header using JWT decoding.
- *
- * Extracts API key from either the 'x-api-key' header or 'apiKey' query parameter
- * and decodes it using the JWT service.
- *
- * @param options.source - Where to look for the API key: 'header', 'query', or 'all'
- *
- * @example
- * ```typescript
- * import { authAPIKey } from '@pikku/core/middleware'
- *
- * addHTTPMiddleware([
- *   authAPIKey({ source: 'header' })
- * ])
- * ```
- */
 export const authAPIKey = pikkuMiddlewareFactory<{
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>

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

@@ -15,7 +15,6 @@ beforeEach(() => {
 
 const createMockHTTPRequest = (headers: Record<string, string> = {}) => ({
   header: (name: string) => {
-    // Check both lowercase and exact case
     return headers[name.toLowerCase()] || headers[name] || null
   },
 })
@@ -102,7 +101,6 @@ describe('authBearer middleware', () => {
     const jwtService = {
       encode: async () => 'token',
       decode: async () => {
-        // Should not be called in static token mode
         assert.fail('JWT decode should not be called in static token mode')
         return null
       },
@@ -268,7 +266,6 @@ describe('authBearer middleware', () => {
     const jwtService = {
       encode: async () => 'token',
       decode: async () => {
-        // Should not be called when static token is provided
         assert.fail('JWT decode should not be called in static token mode')
         return null
       },

package/src/middleware/auth-bearer.ts

@@ -12,46 +12,9 @@ const constantTimeEqual = (a: string, b: string): boolean => {
 }
 
 /**
- * Bearer token middleware that extracts and validates tokens from the Authorization header.
- *
- * Supports three modes:
- * - JWT decoding (default): Decodes bearer tokens using the JWT service
- * - Static token: Provide a `token` object with a value and userSession for simple token validation
- * - Secret-resolved token: Provide a `token` object with a secretId — the expected
- *   value is resolved through the secrets service per request, so it works with any
- *   secret backend and the middleware is a no-op while the secret is unset
- *
- * @param options.token - Optional token configuration: { value, userSession } or { secretId, userSession }
- *
- * @example
- * ```typescript
- * import { authBearer } from '@pikku/core/middleware'
- *
- * // JWT mode (default)
- * addHTTPMiddleware('*', [
- *   authBearer()
- * ])
- *
- * // Static token mode
- * addHTTPMiddleware('*', [
- *   authBearer({
- *     token: {
- *       value: process.env.API_TOKEN,
- *       userSession: { userId: 'system', role: 'admin' }
- *     }
- *   })
- * ])
- *
- * // Secret-resolved token mode
- * addHTTPMiddleware('*', [
- *   authBearer({
- *     token: {
- *       secretId: 'PIKKU_CONSOLE_TOKEN',
- *       userSession: { userId: 'pikku-console-token' }
- *     }
- *   })
- * ])
- * ```
+ * Validates a bearer token: JWT-decoded by default, or compared in constant
+ * time against a static `value` or a `secretId` resolved through the secrets
+ * service per request.
  */
 export const authBearer = pikkuMiddlewareFactory<{
   token?:

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

@@ -117,7 +117,6 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Simulate session change
         SessionService.set(mockUserSession)
       }
     )
@@ -381,7 +380,6 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Simulate session change
         SessionService.set(mockUserSession)
       }
     )
@@ -425,12 +423,10 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Simulate session change
         SessionService.set(mockUserSession)
       }
     )
 
-    // Should complete without errors even though response is not available
     assert.equal(SessionService.get(), mockUserSession)
   })
 
@@ -468,7 +464,6 @@ describe('authCookie middleware', () => {
         },
       } as any,
       async () => {
-        // Modify session to trigger cookie setting
         SessionService.set({ ...mockUserSession, extra: 'data' })
       }
     )
@@ -519,7 +514,6 @@ describe('authCookie middleware', () => {
     const expiresDate = setCookies[0].options.expires
     assert(expiresDate instanceof Date)
 
-    // Expiration should be approximately 15 minutes from now
     const expectedExpiry = new Date(beforeTime.getTime() + 15 * 60 * 1000)
     const timeDiff = Math.abs(expiresDate.getTime() - expectedExpiry.getTime())
     // Allow 5 second tolerance for test execution time

package/src/middleware/auth-cookie.ts

@@ -4,32 +4,8 @@ import type { RelativeTimeInput } from '../time-utils.js'
 import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
 
 /**
- * Cookie-based session middleware that uses JWT for encoding/decoding session data.
- *
- * Reads session from a cookie on incoming requests and automatically updates the cookie
- * when the session changes (e.g., after login).
- *
- * @param options.name - Cookie name
- * @param options.expiresIn - Cookie expiration time (e.g., { value: 30, unit: 'day' })
- * @param options.options - Cookie serialization options (httpOnly, secure, sameSite, etc.)
- *
- * @example
- * ```typescript
- * import { authCookie } from '@pikku/core/middleware'
- *
- * addHTTPMiddleware([
- *   authCookie({
- *     name: 'session',
- *     expiresIn: { value: 30, unit: 'day' },
- *     options: {
- *       httpOnly: true,
- *       secure: true,
- *       sameSite: 'strict',
- *       path: '/'
- *     }
- *   })
- * ])
- * ```
+ * Reads a JWT session from a cookie, and re-issues the cookie after the
+ * request whenever the session changed (e.g. after login).
  */
 export const authCookie = pikkuMiddlewareFactory<{
   name: string

package/src/middleware/cors.test.ts

@@ -243,6 +243,40 @@ describe('cors', () => {
       )
     })
 
+    test('should not expose any headers by default', async () => {
+      const middleware = cors()
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Expose-Headers'],
+        undefined
+      )
+    })
+
+    test('should set exposed headers', async () => {
+      const middleware = cors({ exposeHeaders: ['X-Custom', 'X-Other'] })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Expose-Headers'],
+        'X-Custom, X-Other'
+      )
+    })
+
     test('should not set Vary when origin is string', async () => {
       const middleware = cors({ origin: 'https://example.com' })
       const request = createMockRequest()

package/src/middleware/cors.ts

@@ -1,44 +1,15 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
 /**
- * CORS middleware that handles cross-origin requests including OPTIONS preflight.
- *
- * Sets appropriate CORS headers on all responses and short-circuits OPTIONS
- * preflight requests with a 204 No Content response.
- *
- * @param options.origin - Allowed origin(s). Use `'*'` for any origin, `true` to reflect the request origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
- * @param options.methods - Allowed HTTP methods. Defaults to common methods.
- * @param options.headers - Allowed request headers. Defaults to common headers.
- * @param options.credentials - Whether to allow credentials. Defaults to `false`.
- * @param options.maxAge - Preflight cache duration in seconds. Defaults to `86400` (24 hours).
- *
- * @example
- * ```typescript
- * import { cors } from '@pikku/core/middleware'
- *
- * // Allow all origins
- * addHTTPMiddleware('*', [cors()])
- *
- * // Specific origin with credentials
- * addHTTPMiddleware('*', [
- *   cors({
- *     origin: 'https://app.example.com',
- *     credentials: true,
- *   })
- * ])
- *
- * // Multiple origins
- * addHTTPMiddleware('*', [
- *   cors({
- *     origin: ['https://app.example.com', 'https://admin.example.com'],
- *   })
- * ])
- * ```
+ * Sets CORS headers on every response and short-circuits OPTIONS preflight
+ * with a 204. `origin: true` reflects the request origin; an array reflects a
+ * matching origin and otherwise falls back to its first entry.
  */
 export const cors = pikkuMiddlewareFactory<{
   origin?: string | string[] | true
   methods?: string[]
   headers?: string[]
+  exposeHeaders?: string[]
   credentials?: boolean
   maxAge?: number
 }>(
@@ -46,6 +17,7 @@ export const cors = pikkuMiddlewareFactory<{
     origin = '*',
     methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
     headers = ['Content-Type', 'Authorization', 'x-api-key'],
+    exposeHeaders = [],
     credentials = false,
     maxAge = 86400,
   } = {}) => {
@@ -83,6 +55,13 @@ export const cors = pikkuMiddlewareFactory<{
         response.header('Access-Control-Allow-Methods', methods.join(', '))
         response.header('Access-Control-Allow-Headers', headers.join(', '))
 
+        if (exposeHeaders.length > 0) {
+          response.header(
+            'Access-Control-Expose-Headers',
+            exposeHeaders.join(', ')
+          )
+        }
+
         if (credentials) {
           response.header('Access-Control-Allow-Credentials', 'true')
         }

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

@@ -3,13 +3,13 @@ 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'
 
 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) => {
@@ -354,9 +354,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 +412,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 +444,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) => {
@@ -17,6 +21,8 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
       }
       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', () => {