@pikku/core 0.12.71 → 0.12.74

package/src/handle-error.test.ts

@@ -1,11 +1,12 @@
 import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert'
 import { handleHTTPError } from './handle-error.js'
-import { addError } from './errors/error-handler.js'
+import { addError, PikkuError } from './errors/error-handler.js'
 import {
   NotFoundError,
   BadRequestError,
   ForbiddenError,
+  MissingScopeError,
 } from './errors/errors.js'
 import { resetPikkuState } from './pikku-state.js'
 
@@ -399,6 +400,112 @@ describe('handleHTTPError', () => {
     assert.deepStrictEqual(http._state.jsonBody, { errorId: 'tracker-str' })
   })
 
+  test('should not leak the payload of a registered server error', () => {
+    class LeakyInternalError extends PikkuError {}
+    addError(LeakyInternalError, {
+      status: 500,
+      message: 'Something went wrong',
+    })
+
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new LeakyInternalError(
+      'connection to 10.0.0.1 refused'
+    ) as any
+    error.payload = { connectionString: 'postgres://user:hunter2@10.0.0.1' }
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-leak',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.strictEqual(http._state.jsonBody.payload, undefined)
+  })
+
+  test('should not leak the raw message of a registered server error', () => {
+    class InternalMessageError extends PikkuError {}
+    addError(InternalMessageError, {
+      status: 500,
+      message: 'Something went wrong',
+    })
+
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new InternalMessageError('secret internal detail')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-msg',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.strictEqual(http._state.jsonBody.message, 'Something went wrong')
+  })
+
+  test('should keep the payload of a client facing error', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new MissingScopeError('admin:write')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-scope',
+      logger as any,
+      [],
+      true,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 403)
+    assert.deepStrictEqual(http._state.jsonBody.payload, {
+      error: 'missing_scope',
+      scope: 'admin:write',
+    })
+    assert.strictEqual(
+      http._state.jsonBody.message,
+      'Missing required scope: admin:write'
+    )
+  })
+
+  test('should expose server error details when exposeErrors is true', () => {
+    class ExposableInternalError extends PikkuError {}
+    addError(ExposableInternalError, {
+      status: 500,
+      message: 'Something went wrong',
+    })
+
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new ExposableInternalError('internal detail') as any
+    error.payload = { debug: true }
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-expose-known',
+      logger as any,
+      [],
+      true,
+      false,
+      true
+    )
+
+    assert.strictEqual(http._state.jsonBody.message, 'internal detail')
+    assert.deepStrictEqual(http._state.jsonBody.payload, { debug: true })
+  })
+
   test('should handle warning log without trackerId', () => {
     const logger = createMockLogger()
     const http = createMockHTTP()

package/src/handle-error.ts

@@ -4,17 +4,6 @@ import { NotFoundError } from './errors/errors.js'
 import type { Logger } from './services/logger.js'
 import type { PikkuHTTP } from './wirings/http/http.types.js'
 
-/**
- * Handle errors that occur during route processing
- *
- * @param {any} e - The error that occurred
- * @param {PikkuHTTP | undefined} http - HTTP wire object
- * @param {string} traceId - Unique ID for tracking this error
- * @param {Logger} logger - Logger service
- * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
- * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
- * @param {boolean} bubbleError - Whether to throw the error after handling
- */
 export const handleHTTPError = (
   e: any,
   http: PikkuHTTP | undefined,
@@ -25,27 +14,29 @@ export const handleHTTPError = (
   bubbleError: boolean,
   exposeErrors: boolean = false
 ) => {
-  // Skip 404 handling if configured to do so
   if (e instanceof NotFoundError && !respondWith404) {
     return
   }
 
-  // Get appropriate error response
   const errorResponse = getErrorResponse(e)
   if (errorResponse != null) {
-    // Set status and response body
+    const clientFacing =
+      errorResponse.status < 500 || (exposeErrors && !isProduction())
+
     http?.response?.status(errorResponse.status)
     http?.response?.json({
       name: e instanceof Error ? e.name : undefined,
       message:
-        e instanceof Error && e.message && e.message !== 'An error occurred'
+        clientFacing &&
+        e instanceof Error &&
+        e.message &&
+        e.message !== 'An error occurred'
           ? e.message
           : errorResponse.message,
-      payload: (e as any).payload,
+      payload: clientFacing ? (e as any).payload : undefined,
       errorId: traceId,
     })
 
-    // Log certain status codes as warnings
     if (logWarningsForStatusCodes.includes(errorResponse.status)) {
       if (traceId) {
         logger.warn(`Warning id: ${traceId}`)
@@ -53,7 +44,6 @@ export const handleHTTPError = (
       logger.warn(e instanceof Error ? e.message : e)
     }
   } else {
-    // Handle unexpected errors
     logger.error(e instanceof Error ? e.message : e)
     http?.response?.status(500)
 

package/src/index.ts

@@ -10,8 +10,10 @@ export type {
   CorePikkuMiddlewareFactory,
   CorePikkuMiddlewareGroup,
   CoreServices,
+  CoreSecretlessSingletonServices,
   CoreSingletonServices,
   CoreUserSession,
+  SecretlessServices,
   CreateConfig,
   ServerLifecycle,
   FunctionMeta,
@@ -89,6 +91,13 @@ export {
   parseVersionedId,
 } from './version.js'
 export { runPikkuFunc } from './function/function-runner.js'
+export {
+  AbandonedError,
+  beginChanges,
+  getAbortScope,
+  runInAbortScope,
+  type AbortScope,
+} from './function/abort-scope.js'
 export { runCLICommand, pikkuCLIRender } from './wirings/cli/cli-runner.js'
 export { fetch } from './wirings/http/http-runner.js'
 export {
@@ -103,7 +112,49 @@ export type {
 } from './wirings/mcp/mcp.types.js'
 export { runQueueJob } from './wirings/queue/queue-runner.js'
 export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js'
-export { NotFoundError } from './errors/errors.js'
+export {
+  AIProviderAuthError,
+  AIProviderNotConfiguredError,
+  BadGatewayError,
+  BadRequestError,
+  ConflictError,
+  ExpectationFailedError,
+  ForbiddenError,
+  GatewayTimeoutError,
+  GoneError,
+  HTTPVersionNotSupportedError,
+  InternalServerError,
+  InvalidMiddlewareWireError,
+  InvalidOriginError,
+  InvalidSessionError,
+  LengthRequiredError,
+  LocalEnvironmentOnlyError,
+  LockedError,
+  MaxComputeTimeReachedError,
+  MethodNotAllowedError,
+  MissingCredentialError,
+  MissingSchemaError,
+  MissingScopeError,
+  MissingServiceError,
+  MissingSessionError,
+  NotAcceptableError,
+  NotFoundError,
+  NotImplementedError,
+  PayloadTooLargeError,
+  PaymentRequiredError,
+  PikkuMissingMetaError,
+  PreconditionFailedError,
+  ProxyAuthenticationRequiredError,
+  RangeNotSatisfiableError,
+  ReadonlySessionError,
+  RequestTimeoutError,
+  ServiceUnavailableError,
+  TooManyRequestsError,
+  URITooLongError,
+  UnauthorizedError,
+  UnprocessableContentError,
+  UnsupportedMediaTypeError,
+} from './errors/errors.js'
 export { PikkuError, isExpectedError } from './errors/error-handler.js'
 export type { EventHubService } from './wirings/channel/eventhub-service.js'
 export type { QueueService } from './wirings/queue/queue.types.js'
@@ -118,6 +169,14 @@ export type {
   SendTextEmailInput,
 } from './services/email-service.js'
 export type { SecretService } from './services/secret-service.js'
+export {
+  SecretAccessDeniedError,
+  withoutSecrets,
+} from './services/secretless.js'
+export {
+  SecretHostNotAllowedError,
+  assertSecretAllowedForHost,
+} from './services/secret-host-binding.js'
 export type { VariablesService } from './services/variables-service.js'
 export type {
   ContentService,

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) {