@pikku/core 0.12.71 → 0.12.72

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

@@ -14,6 +14,8 @@ import type { PikkuHTTP } from './wirings/http/http.types.js'
  * @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
+ * @param {boolean} exposeErrors - Whether to include internal error details (message, stack and
+ * payload of 5xx errors) in the response body. Ignored in production.
  */
 export const handleHTTPError = (
   e: any,
@@ -33,15 +35,21 @@ export const handleHTTPError = (
   // Get appropriate error response
   const errorResponse = getErrorResponse(e)
   if (errorResponse != null) {
+    const clientFacing =
+      errorResponse.status < 500 || (exposeErrors && !isProduction())
+
     // Set status and response body
     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,
     })
 

package/src/schema.test.ts

@@ -3,6 +3,7 @@ import * as assert from 'assert'
 import {
   addSchema,
   getSchema,
+  applyDefaultsFromSchema,
   coerceTopLevelDataFromSchema,
   validateSchema,
   compileAllSchemas,
@@ -111,6 +112,108 @@ describe('Schema', () => {
     })
   })
 
+  describe('applyDefaultsFromSchema', () => {
+    before(() => {
+      addSchema('defaultsSchema', {
+        properties: {
+          page: { type: 'number', default: 1 },
+          limit: { type: 'number', default: 50 },
+          addons: { type: 'array', default: [] },
+          mode: { type: 'string', default: 'manual' },
+          enabled: { type: 'boolean', default: true },
+          name: { type: 'string' },
+        },
+      })
+
+      addSchema('noDefaultsSchema', {
+        properties: { name: { type: 'string' } },
+      })
+
+      addSchema('booleanPropSchema', {
+        properties: { isActive: true, page: { type: 'number', default: 1 } },
+      })
+    })
+
+    test('should fill in absent properties from their default', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {})
+      assert.strictEqual(data.page, 1)
+      assert.strictEqual(data.limit, 50)
+      assert.strictEqual(data.mode, 'manual')
+      assert.strictEqual(data.enabled, true)
+    })
+
+    test('should not overwrite a supplied value', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {
+        page: 7,
+        limit: 200,
+      })
+      assert.strictEqual(data.page, 7)
+      assert.strictEqual(data.limit, 200)
+    })
+
+    // `false` and `0` are the values a truthiness check silently replaces, and
+    // the reason this tests presence rather than falsiness.
+    test('should not overwrite a supplied falsy value', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {
+        page: 0,
+        enabled: false,
+      })
+      assert.strictEqual(data.page, 0)
+      assert.strictEqual(data.enabled, false)
+    })
+
+    test('should fill defaults into nullish data', () => {
+      assert.strictEqual(
+        applyDefaultsFromSchema('defaultsSchema', undefined).page,
+        1
+      )
+      assert.strictEqual(
+        applyDefaultsFromSchema('defaultsSchema', null).limit,
+        50
+      )
+    })
+
+    test('should leave properties without a default absent', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {})
+      assert.ok(!('name' in data))
+    })
+
+    // Two requests sharing one array default would let the first request's
+    // pushes show up in the second.
+    test('should clone object and array defaults per call', () => {
+      const first = applyDefaultsFromSchema('defaultsSchema', {})
+      const second = applyDefaultsFromSchema('defaultsSchema', {})
+      first.addons.push('leaked')
+      assert.deepStrictEqual(second.addons, [])
+    })
+
+    test('should return the same data when the schema has no defaults', () => {
+      const data = { name: 'x' }
+      assert.strictEqual(
+        applyDefaultsFromSchema('noDefaultsSchema', data),
+        data
+      )
+    })
+
+    test('should return data untouched for an unknown schema', () => {
+      const data = { name: 'x' }
+      assert.strictEqual(applyDefaultsFromSchema('nonExistent', data), data)
+    })
+
+    test('should leave a primitive body for the validator to reject', () => {
+      assert.strictEqual(
+        applyDefaultsFromSchema('defaultsSchema', 'nope'),
+        'nope'
+      )
+    })
+
+    test('should skip boolean schema properties', () => {
+      const data = applyDefaultsFromSchema('booleanPropSchema', {})
+      assert.strictEqual(data.page, 1)
+      assert.ok(!('isActive' in data))
+    })
+  })
+
   describe('validateSchema', () => {
     beforeEach(() => {
       resetPikkuState()

package/src/schema.ts

@@ -94,6 +94,57 @@ 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.
+ */
+export const applyDefaultsFromSchema = (
+  schemaName: string,
+  data: any,
+  packageName: string | null = null
+) => {
+  const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName)
+  if (!schema?.properties) return data
+
+  // A primitive body cannot carry named properties; leave it for the validator
+  // to reject rather than reshaping it into something that would pass.
+  if (data != null && typeof data !== 'object') return data
+
+  let result = data
+  for (const key in schema.properties) {
+    const property = schema.properties[key]
+    if (typeof property === 'boolean' || !('default' in property)) {
+      continue
+    }
+    // Allocated only once a default is actually found, so a schema without any
+    // leaves the caller's data (and its absence) exactly as it was.
+    result ??= {}
+    if (result[key] === undefined) {
+      result[key] = structuredClone(property.default)
+    }
+  }
+  return result
+}
+
 export const coerceTopLevelDataFromSchema = (
   schemaName: string,
   data: any,

package/src/wirings/http/http-runner.ts

@@ -531,6 +531,7 @@ export const fetchData = async <In, Out>(
     exposeErrors = !isProduction(),
     generateRequestId,
     traceId: externalTraceId,
+    maxBodySize,
   }: RunHTTPWiringOptions = {}
 ): Promise<Out | void> => {
   const singletonServices = getSingletonServices()
@@ -540,7 +541,9 @@ export const fetchData = async <In, Out>(
 
   // Combine the request and response into one wire object
   const pikkuRequest =
-    request instanceof Request ? new PikkuFetchHTTPRequest(request) : request
+    request instanceof Request
+      ? new PikkuFetchHTTPRequest(request, { maxBodySize })
+      : request
 
   // Resolve traceId: external (e.g. CF-Ray) > x-request-id header > generated
   let requestId: string | null = externalTraceId ?? null

package/src/wirings/http/http.types.ts

@@ -38,6 +38,8 @@ export type RunHTTPWiringOptions = Partial<{
   generateRequestId: () => string
   /** Pre-resolved trace ID (e.g. CF-Ray). Falls back to x-request-id header or generated ID. */
   traceId: string
+  /** Maximum request body size in bytes, applied when pikku wraps a fetch `Request`. */
+  maxBodySize: number
 }>
 
 /**

package/src/wirings/http/index.ts

@@ -1,4 +1,8 @@
-export { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
+export {
+  PikkuFetchHTTPRequest,
+  DEFAULT_MAX_BODY_SIZE,
+} from './pikku-fetch-http-request.js'
+export type { PikkuFetchHTTPRequestOptions } from './pikku-fetch-http-request.js'
 export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 export { logRoutes } from './log-http-routes.js'
 

package/src/wirings/http/pikku-fetch-http-request.test.ts

@@ -221,6 +221,95 @@ test('data() throws on boolean conflict', async () => {
 
 // --- Safe fallback: only one source
 
+// --- Body size limits
+
+const streamedRequest = (chunks) =>
+  new Request('http://localhost', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: new ReadableStream({
+      start(controller) {
+        for (const chunk of chunks) {
+          controller.enqueue(new TextEncoder().encode(chunk))
+        }
+        controller.close()
+      },
+    }),
+    duplex: 'half',
+  })
+
+test('arrayBuffer() rejects a body larger than the configured limit', async () => {
+  const req = new Request('http://localhost', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/octet-stream' },
+    body: 'x'.repeat(64),
+  })
+  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
+  await assert.rejects(async () => await pikkuReq.arrayBuffer(), {
+    name: 'PayloadTooLargeError',
+  })
+})
+
+test('arrayBuffer() rejects an oversized body with no content-length header', async () => {
+  const req = streamedRequest(['x'.repeat(32), 'y'.repeat(32)])
+  assert.equal(req.headers.get('content-length'), null)
+  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
+  await assert.rejects(async () => await pikkuReq.arrayBuffer(), {
+    name: 'PayloadTooLargeError',
+  })
+})
+
+test('arrayBuffer() rejects a body whose content-length under-reports its size', async () => {
+  const req = new Request('http://localhost', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': '4',
+    },
+    body: new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('z'.repeat(128)))
+        controller.close()
+      },
+    }),
+    duplex: 'half',
+  })
+  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
+  await assert.rejects(async () => await pikkuReq.arrayBuffer(), {
+    name: 'PayloadTooLargeError',
+  })
+})
+
+test('data() surfaces PayloadTooLargeError rather than wrapping it', async () => {
+  const req = createRequest(
+    'POST',
+    'http://localhost',
+    { padding: 'x'.repeat(256) },
+    { 'Content-Type': 'application/json' }
+  )
+  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
+  await assert.rejects(async () => await pikkuReq.data(), {
+    name: 'PayloadTooLargeError',
+  })
+})
+
+test('data() accepts a body within the configured limit', async () => {
+  const req = createRequest(
+    'POST',
+    'http://localhost',
+    { ok: true },
+    { 'Content-Type': 'application/json' }
+  )
+  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 1024 })
+  assert.deepEqual(await pikkuReq.data(), { ok: true })
+})
+
+test('data() accepts a streamed body within the default limit', async () => {
+  const req = streamedRequest(['{"ok"', ':true}'])
+  const pikkuReq = new PikkuFetchHTTPRequest(req)
+  assert.deepEqual(await pikkuReq.data(), { ok: true })
+})
+
 test('data() works when only body has values', async () => {
   const req = createRequest(
     'POST',

package/src/wirings/http/pikku-fetch-http-request.ts

@@ -1,7 +1,22 @@
 import { parse as parseQuery } from 'picoquery'
 import { parse as parseCookie } from 'cookie'
 import type { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js'
-import { UnprocessableContentError } from '../../errors/errors.js'
+import {
+  PayloadTooLargeError,
+  UnprocessableContentError,
+} from '../../errors/errors.js'
+
+/**
+ * The largest request body read into memory when no limit is configured. Ample
+ * for JSON APIs and typical uploads while keeping a single request's memory
+ * footprint bounded.
+ */
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024
+
+export type PikkuFetchHTTPRequestOptions = Partial<{
+  /** Maximum request body size in bytes. Defaults to {@link DEFAULT_MAX_BODY_SIZE}. */
+  maxBodySize: number
+}>
 
 /**
  * Abstract class representing a pikku request.
@@ -17,9 +32,14 @@ export class PikkuFetchHTTPRequest<
   #rawBodyText: string | undefined
   #rawBodyBuffer: ArrayBuffer | undefined
   #rawBufferPromise: Promise<ArrayBuffer> | undefined
+  #maxBodySize: number
 
-  constructor(private request: Request) {
+  constructor(
+    private request: Request,
+    { maxBodySize = DEFAULT_MAX_BODY_SIZE }: PikkuFetchHTTPRequestOptions = {}
+  ) {
     this.#url = new URL(request.url)
+    this.#maxBodySize = maxBodySize
   }
 
   public method(): HTTPMethod {
@@ -78,13 +98,72 @@ export class PikkuFetchHTTPRequest<
       )
       return this.#rawBufferPromise
     }
-    this.#rawBufferPromise = this.request.arrayBuffer().then((buf) => {
+    this.#rawBufferPromise = this.#readBoundedBuffer().then((buf) => {
       this.#rawBodyBuffer = buf
       return buf
     })
     return this.#rawBufferPromise
   }
 
+  /**
+   * Reads the body while refusing to buffer more than `maxBodySize` bytes. The
+   * declared `content-length` is rejected up front so an oversized body is never
+   * transferred, and the stream is measured as it arrives because that header is
+   * both optional and attacker-controlled.
+   */
+  async #readBoundedBuffer(): Promise<ArrayBuffer> {
+    const contentLength = this.request.headers.get('content-length')
+    if (contentLength !== null) {
+      const declaredSize = Number(contentLength)
+      if (Number.isFinite(declaredSize) && declaredSize > this.#maxBodySize) {
+        throw this.#payloadTooLarge()
+      }
+    }
+
+    const stream = this.request.body
+    if (stream === null) {
+      const buffer = await this.request.arrayBuffer()
+      if (buffer.byteLength > this.#maxBodySize) {
+        throw this.#payloadTooLarge()
+      }
+      return buffer
+    }
+
+    const reader = stream.getReader()
+    const chunks: Uint8Array[] = []
+    let size = 0
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) {
+          break
+        }
+        size += value.byteLength
+        if (size > this.#maxBodySize) {
+          await reader.cancel()
+          throw this.#payloadTooLarge()
+        }
+        chunks.push(value)
+      }
+    } finally {
+      reader.releaseLock()
+    }
+
+    const body = new Uint8Array(size)
+    let offset = 0
+    for (const chunk of chunks) {
+      body.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    return body.buffer as ArrayBuffer
+  }
+
+  #payloadTooLarge(): PayloadTooLargeError {
+    return new PayloadTooLargeError(
+      `Request body exceeds the maximum size of ${this.#maxBodySize} bytes`
+    )
+  }
+
   async #readRawText(): Promise<string> {
     if (this.#rawBodyText !== undefined) {
       return this.#rawBodyText
@@ -214,6 +293,9 @@ export class PikkuFetchHTTPRequest<
         )
       }
     } catch (e) {
+      if (e instanceof PayloadTooLargeError) {
+        throw e
+      }
       throw new UnprocessableContentError(`Error parsing body: ${e}`)
     }
     return body

package/src/wirings/mcp/mcp-runner.test.ts

@@ -329,6 +329,46 @@ describe('runMCPTool', () => {
       }
     )
   })
+
+  test('withholds the error message and stack from internal MCP errors in production', async () => {
+    pikkuState(null, 'mcp', 'toolsMeta').prodBoom = {
+      name: 'prodBoom',
+      title: 'Prod Boom',
+      description: 'Prod Boom',
+      pikkuFuncId: 'prodBoomFunc',
+      inputSchema: null,
+      outputSchema: null,
+    } as never
+    registerFunction('prodBoomFunc', async () => {
+      throw new Error('secret internal detail')
+    })
+
+    const originalNodeEnv = process.env.NODE_ENV
+    process.env.NODE_ENV = 'production'
+    try {
+      await assert.rejects(
+        () =>
+          runMCPTool(
+            { jsonrpc: '2.0', id: 'prod-boom-1', params: {} },
+            { mcp: mcpWire as never },
+            'prodBoom'
+          ),
+        (error: unknown) => {
+          assert.ok(error instanceof MCPError)
+          assert.equal(error.error.code, -32603)
+          assert.equal(error.error.message, 'Internal error')
+          assert.equal(error.error.data, undefined)
+          return true
+        }
+      )
+    } finally {
+      if (originalNodeEnv === undefined) {
+        delete process.env.NODE_ENV
+      } else {
+        process.env.NODE_ENV = originalNodeEnv
+      }
+    }
+  })
 })
 
 describe('runMCPPrompt', () => {

package/src/wirings/mcp/mcp-runner.ts

@@ -12,6 +12,7 @@ import type {
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
 import { getErrorResponse } from '../../errors/error-handler.js'
+import { isProduction } from '../../env.js'
 import { closeWireServices } from '../../utils.js'
 import {
   pikkuState,
@@ -35,6 +36,11 @@ export class MCPError extends Error {
 
 export type RunMCPEndpointParams<Tools extends string = any> = {
   mcp?: PikkuMCP<Tools>
+  /**
+   * Surface the error message + stack on unexpected internal errors.
+   * Defaults to enabled outside of production.
+   */
+  exposeErrors?: boolean
 }
 
 export type JsonRpcError = {
@@ -187,7 +193,7 @@ async function runMCPPikkuFunc(
   name: string,
   mcp: CoreMCPResource | CoreMCPPrompt | undefined,
   pikkuFuncId: string | undefined,
-  { mcp: mcpWire }: RunMCPEndpointParams
+  { mcp: mcpWire, exposeErrors = !isProduction() }: RunMCPEndpointParams
 ): Promise<JsonRpcResponse> {
   const singletonServices = getSingletonServices()
   const createWireServices = getCreateWireServices()
@@ -289,7 +295,10 @@ async function runMCPPikkuFunc(
         id: request.id,
         code: -32603,
         message: 'Internal error',
-        data: { message: e.message, stack: e.stack },
+        data:
+          exposeErrors && !isProduction() && e instanceof Error
+            ? { message: e.message, stack: e.stack }
+            : undefined,
       })
     }
   } finally {