@c9up/ream 0.2.28 → 0.2.30

package/src/bodyparser/BodyParserMiddleware.ts

@@ -21,11 +21,11 @@ export interface BodyParserConfig {
    */
   allowedMethods?: string[]
   json?: {
-    limit?: string // e.g. '1mb'
+    limit?: string | number // e.g. '1mb', '1.5 mb' or a number of bytes
     types?: string[]
   }
   form?: {
-    limit?: string
+    limit?: string | number
     types?: string[]
     /**
      * Turn `''` into `null`. AdonisJS defaults this to `true`, so an empty
@@ -39,12 +39,12 @@ export interface BodyParserConfig {
     queryString?: QsParseOptions
   }
   raw?: {
-    limit?: string
+    limit?: string | number
     types?: string[]
   }
   multipart?: {
     /** Total multipart body size cap (sum of all file sizes). Default: '20mb'. */
-    limit?: string
+    limit?: string | number
     /**
      * Maximum number of files per request. AdonisJS has no such option — it
      * bounds a multipart body by total size and field count only, so ten
@@ -98,6 +98,8 @@ const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
 
 export default class BodyParserMiddleware {
   #config: ResolvedBodyParserConfig
+  /** Each section's limit in bytes, read once so a bad size fails at boot. */
+  readonly #limits: { json: number; form: number; raw: number; multipart: number }
 
   constructor(explicitConfig: BodyParserConfig | undefined = undefined) {
     // The default value is load-bearing: an OPTIONAL parameter still counts
@@ -118,6 +120,12 @@ export default class BodyParserMiddleware {
       raw: { ...DEFAULT_CONFIG.raw, ...config?.raw },
       multipart: { ...DEFAULT_CONFIG.multipart, ...config?.multipart },
     }
+    this.#limits = {
+      json: parseSize(this.#config.json.limit),
+      form: parseSize(this.#config.form.limit),
+      raw: parseSize(this.#config.raw.limit),
+      multipart: parseSize(this.#config.multipart.limit),
+    }
   }
 
   async handle(ctx: HttpContext, next: () => Promise<void>) {
@@ -136,18 +144,22 @@ export default class BodyParserMiddleware {
     }
 
     const contentType = ctx.request.header('content-type') ?? ''
+    // A body over its native limit (`bodyTooLarge`) was never kept: `raw()`
+    // throws the same 413 below instead of handing back an empty string. The
+    // route is already matched here, so an unknown URL answered 404 first.
     const rawBody = ctx.request.raw()
 
     // Size check. Thrown rather than written: the app's exception handler
     // negotiates the response, so an HTML app gets an error page instead of a
     // JSON envelope it never asked for — and can override the rendering.
-    if (Buffer.byteLength(rawBody, 'utf8') > parseSize(this.#getLimit(contentType))) {
+    if (Buffer.byteLength(rawBody, 'utf8') > this.#getLimit(contentType)) {
       throw entityTooLarge('request entity too large')
     }
 
-    // JSON
+    // JSON — parsed here and only here, under one of `json.types`. A body
+    // with any other media type (or none) is never read as JSON.
     if (matchesType(contentType, this.#config.json.types)) {
-      // `Request` lazy-parses JSON on first read; nothing to do here.
+      ctx.request.setParsedBody(parseJsonBody(rawBody))
     }
 
     // Form URL-encoded
@@ -188,11 +200,11 @@ export default class BodyParserMiddleware {
     await next()
   }
 
-  #getLimit(contentType: string): string {
-    if (matchesType(contentType, this.#config.json.types)) return this.#config.json.limit
-    if (matchesType(contentType, this.#config.form.types)) return this.#config.form.limit
-    if (matchesType(contentType, this.#config.multipart.types)) return this.#config.multipart.limit
-    return this.#config.raw.limit
+  #getLimit(contentType: string): number {
+    if (matchesType(contentType, this.#config.json.types)) return this.#limits.json
+    if (matchesType(contentType, this.#config.form.types)) return this.#limits.form
+    if (matchesType(contentType, this.#config.multipart.types)) return this.#limits.multipart
+    return this.#limits.raw
   }
 
   /**
@@ -214,12 +226,30 @@ export default class BodyParserMiddleware {
     }
 
     const totalBytes = files.reduce((sum, f) => sum + f.size, 0)
-    if (totalBytes > parseSize(cfg.limit)) {
+    if (totalBytes > this.#limits.multipart) {
       throw entityTooLarge('request entity too large')
     }
   }
 }
 
+/**
+ * A JSON body as the request body: an object as is, any other JSON value under
+ * `_body` (the shape the raw-text parser uses), and `{}` for malformed JSON.
+ */
+function parseJsonBody(raw: string): Record<string, unknown> {
+  if (raw.length === 0) return {}
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return {}
+  }
+  if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    return { ...parsed }
+  }
+  return { _body: parsed }
+}
+
 /** The one exception every body-size limit raises (AdonisJS parity). */
 function entityTooLarge(message: string): Exception {
   return new Exception(message, { status: 413, code: 'E_REQUEST_ENTITY_TOO_LARGE' })
@@ -247,8 +277,7 @@ function matchesType(contentType: string, types: string[]): boolean {
 
 /**
  * `enabled` was an atlas-era invention: AdonisJS has no such flag, and a parser
- * is turned off by giving it no `types`. It also never worked for JSON, which
- * `Request` lazy-parses on first read regardless.
+ * is turned off by giving it no `types`.
  *
  * Silently ignoring a config key that used to mean something would re-enable a
  * parser an app deliberately switched off, so it fails loudly with the
@@ -275,7 +304,7 @@ function assertNoEnabledFlag(config?: BodyParserConfig): void {
     throw new Error(
       '[E_BODYPARSER_CONFIG] `multipart.tmpDir` is not supported — uploaded files are held in ' +
         'memory and never written to a temporary directory. Choose the destination when you ' +
-        'store the file: `await file.moveToDisk(directory)`.',
+        'store the file: `await file.move(directory)`.',
     )
   }
 }

package/src/bodyparser/MultipartFile.ts

@@ -51,18 +51,27 @@ function isMimeType(value: string): value is MimeType {
  *
  * Like AdonisJS MultipartFile:
  *   const avatar = request.file('avatar', { size: '2mb', extnames: ['jpg', 'png'] })
- *   await avatar.moveToDisk('uploads')
+ *   await avatar.move(app.makePath('uploads'))
+ *
+ * Macroable: a package extends every upload at boot, the way a storage
+ * package adds `moveToDisk(key, disk?, options?)` to write it to a configured
+ * disk. `moveToDisk` is deliberately not defined here, so that macro owns it.
  */
 
 import { randomBytes } from 'node:crypto'
 import { Readable } from 'node:stream'
+import { errorCode } from '../helpers/errors.js'
+import { Macroable } from '../utils/Macroable.js'
+import { parseSize } from './parseSize.js'
+import { parseFormFields } from './qsParse.js'
 
 export interface FileValidationOptions {
-  size?: string
+  /** Largest accepted size: bytes, or a value such as `'2mb'` or `'1.5 mb'`. */
+  size?: string | number
   extnames?: string[]
 }
 
-export class MultipartFile {
+export class MultipartFile extends Macroable {
   /** Original filename from the client. */
   readonly clientName: string
 
@@ -153,6 +162,12 @@ export class MultipartFile {
   /** The name it was written under, once it has been moved. */
   fileName?: string
 
+  /**
+   * Free-form data about the file, for whoever moves it: a storage macro
+   * records the URL of the stored object here.
+   */
+  meta: Record<string, unknown> = {}
+
   /** File size in bytes. */
   readonly size: number
 
@@ -188,6 +203,7 @@ export class MultipartFile {
     type: string
     content: Buffer
   }) {
+    super()
     this.fieldName = options.fieldName
     this.clientName = options.clientName
     this.headers = { 'content-type': options.type }
@@ -272,8 +288,8 @@ export class MultipartFile {
    * spells it.
    */
   validate(options: FileValidationOptions = this.#validationOptions): boolean {
-    if (options.size) {
-      const maxBytes = parseFileSize(options.size)
+    if (options.size !== undefined) {
+      const maxBytes = parseSize(options.size)
       if (this.size > maxBytes) {
         this.errors.push(`File size ${this.size} exceeds limit ${options.size}`)
       }
@@ -318,40 +334,6 @@ export class MultipartFile {
     return this.errors.length === 0
   }
 
-  /**
-   * Move file to a directory on disk. When `name` is supplied it must be
-   * a plain filename — no path separators, no `.`/`..` segments. The
-   * common footgun is passing the client-supplied `clientName` directly
-   * (`await file.moveToDisk('uploads', file.clientName)`); a malicious
-   * upload could otherwise traverse out of `directory` via `../../etc/...`.
-   */
-  async moveToDisk(directory: string, name?: string): Promise<string> {
-    const { mkdirSync, writeFileSync } = await import('node:fs')
-    const { join } = await import('node:path')
-
-    if (name !== undefined && !isSafeFilename(name)) {
-      throw new Error(
-        `MultipartFile.moveToDisk: 'name' must be a plain filename (no path separators, '.', or '..'). Got: ${JSON.stringify(name)}`,
-      )
-    }
-
-    mkdirSync(directory, { recursive: true })
-    const fileName = name ?? `${randomBytes(16).toString('hex')}.${this.extname}`
-    // Defense-in-depth: the default branch interpolates `extname` (derived
-    // from attacker-controlled `clientName`) into the filename, bypassing
-    // the `name` guard above. Re-validate the synthesized fileName before
-    // join to reject a hostile extname (separators, NUL).
-    if (!isSafeFilename(fileName)) {
-      throw new Error(
-        `MultipartFile.moveToDisk: derived filename '${fileName}' is unsafe (separator or invalid char in clientName-derived extname).`,
-      )
-    }
-    const filePath = join(directory, fileName)
-    writeFileSync(filePath, this.content)
-    this.markAsMoved(fileName, filePath)
-    return filePath
-  }
-
   /**
    * Write the file into `location` (AdonisJS `move`).
    *
@@ -360,19 +342,31 @@ export class MultipartFile {
    * construction), so this writes the buffer. There is therefore no
    * `E_MISSING_FILE_TMP_PATH`: there is no temporary file to be missing.
    *
-   * `overwrite` defaults to true, as upstream. The generated name carries the
-   * detected extension, and both it and a caller-supplied `name` go through the
-   * same plain-filename guard {@link moveToDisk} uses — the common footgun is
-   * passing `file.clientName` straight through.
+   * `overwrite` defaults to true, as upstream.
+   *
+   * NAMED DEVIATION — without `name`, upstream writes under `clientName`, a
+   * value the client chose; Ream generates a random name carrying the
+   * detected extension, so an upload neither picks its own path nor
+   * overwrites another one by sharing its name.
+   *
+   * A caller-supplied `name` must be a plain filename (no separator, no `.`
+   * or `..`): the common footgun is passing `file.clientName` straight
+   * through. The generated name is checked too, since its extension comes
+   * from the client's filename when the bytes are not recognised.
    */
   async move(location: string, options?: { name?: string; overwrite?: boolean }): Promise<void> {
     const { mkdir, writeFile } = await import('node:fs/promises')
     const { join } = await import('node:path')
 
+    if (options?.name !== undefined && !isSafeFilename(options.name)) {
+      throw new Error(
+        `MultipartFile.move: 'name' must be a plain filename (no path separators, '.', or '..'). Got: ${JSON.stringify(options.name)}`,
+      )
+    }
     const name = options?.name ?? `${randomBytes(16).toString('hex')}.${this.extname || 'unknown'}`
     if (!isSafeFilename(name)) {
       throw new Error(
-        `MultipartFile.move: 'name' must be a plain filename (no path separators, '.', or '..'). Got: ${JSON.stringify(name)}`,
+        `MultipartFile.move: the derived file name ${JSON.stringify(name)} is unsafe (a separator or NUL in the extension of the client's filename).`,
       )
     }
 
@@ -392,7 +386,7 @@ export class MultipartFile {
     try {
       await writeFile(filePath, this.content, options?.overwrite === false ? { flag: 'wx' } : {})
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      if (errorCode(error) === 'EEXIST') {
         throw new Error(
           `"${name}" already exists at "${location}". Set "overwrite = true" to overwrite it`,
         )
@@ -432,23 +426,6 @@ function isSafeFilename(name: string): boolean {
   return true
 }
 
-function parseFileSize(size: string): number {
-  const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
-  if (!match) return 1024 * 1024
-  const [, digits, unit] = match
-  const num = parseInt(digits ?? '0', 10)
-  switch (unit?.toLowerCase()) {
-    case 'kb':
-      return num * 1024
-    case 'mb':
-      return num * 1024 * 1024
-    case 'gb':
-      return num * 1024 * 1024 * 1024
-    default:
-      return num
-  }
-}
-
 /**
  * Hydrate `MultipartFile` instances from the typed payload the Rust
  * HyperServer attaches to the request. The wire-level parser (multer crate,
@@ -464,11 +441,13 @@ export function hydrateMultipartPayload(payload: {
     size: number
     contentB64: string
   }>
-}): { fields: Record<string, string>; files: MultipartFile[] } {
-  const fields: Record<string, string> = {}
-  for (const field of payload.fields) {
-    fields[field.name] = field.value
-  }
+}): { fields: Record<string, unknown>; files: MultipartFile[] } {
+  // Nested and collected exactly like a urlencoded body: `tags[]` repeated is
+  // an array, `user[name]` an object. Flat, a repeated name kept only its
+  // last value once a file input was added to the form.
+  // The multipart part count is already bounded natively (`maxFields`), so
+  // no parameter cap applies on top of it here.
+  const fields = parseFormFields(payload.fields, { parameterLimit: Number.POSITIVE_INFINITY })
   const files = payload.files.map(
     (f) =>
       new MultipartFile({

package/src/bodyparser/parseSize.ts

@@ -1,21 +1,21 @@
+import { ReamError } from '../errors/ReamError.js'
+import { parse } from '../helpers/bytes.js'
+
 /**
- * Parse a human-readable size string (e.g. '1mb', '512kb', '2gb') to bytes.
- * Single source of truth, imported by BodyParserMiddleware (which previously
- * carried an identical inline copy — consolidated 2026-06-15).
+ * Read a size limit (`'1mb'`, `'50 mb'`, `'1.5kb'`, `1024`) into bytes, with
+ * the `bytes` grammar every size option of the body parser accepts.
+ *
+ * Throws on anything it cannot read, or on a negative size. A silent fallback
+ * is what turned `limit: '50 mb'` into a 1 MB cap with no word: a limit the
+ * application did not set is worse than a boot that refuses to start.
  */
-export function parseSize(size: string): number {
-  const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
-  if (!match) return 1024 * 1024 // default 1mb
-  const [, digits, unit] = match
-  const num = parseInt(digits ?? '0', 10)
-  switch (unit?.toLowerCase()) {
-    case 'kb':
-      return num * 1024
-    case 'mb':
-      return num * 1024 * 1024
-    case 'gb':
-      return num * 1024 * 1024 * 1024
-    default:
-      return num
+export function parseSize(size: string | number): number {
+  const bytes = parse(size)
+  if (bytes === null || !Number.isFinite(bytes) || bytes < 0) {
+    throw new ReamError(
+      'E_BODYPARSER_INVALID_SIZE',
+      `Cannot read the size ${JSON.stringify(size)}: expected a number of bytes or a value such as '512kb', '1.5mb' or '2 gb'.`,
+    )
   }
+  return bytes
 }

package/src/bodyparser/qsParse.ts

@@ -11,7 +11,7 @@
  * dependency it can write in a screenful, and the limits below are easier to
  * defend when they are visible.
  *
- * Three guards, all of which `qs` also applies:
+ * Four guards, all of which `qs` also applies:
  *
  *  - **Prototype keys are dropped.** `__proto__[x]=1` in a form body is the
  *    classic prototype-pollution vector; the key never reaches an object.
@@ -19,11 +19,14 @@
  *    as a literal key rather than allocating unbounded nesting.
  *  - **Parameter count is capped** (`qs` defaults to 1000), so a body of a
  *    million `a[0]`, `a[1]`… cannot be turned into a million-entry object.
+ *  - **Explicit array indices are capped** (`qs` `arrayLimit`, default 20).
+ *    A larger index is an object key, so `ids[4294967294]=1` stays one entry.
  */
 
 /** `qs` defaults, reproduced so the behaviour is the same out of the box. */
 export const DEFAULT_DEPTH = 5
 export const DEFAULT_PARAMETER_LIMIT = 1000
+export const DEFAULT_ARRAY_LIMIT = 20
 
 export interface QsParseOptions {
   /**
@@ -34,6 +37,12 @@ export interface QsParseOptions {
   allowDots?: boolean
   depth?: number
   parameterLimit?: number
+  /**
+   * Highest explicit index + 1 that still builds an array (`qs` defaults to
+   * 20). `ids[25]=x` becomes `{ ids: { '25': 'x' } }`, so a 16-byte request
+   * cannot allocate a 100-million-slot array.
+   */
+  arrayLimit?: number
   /** Turn `''` into `null`, as AdonisJS' `convertEmptyStringsToNull` does. */
   convertEmptyStringsToNull?: boolean
   /** Trim surrounding whitespace, as AdonisJS' `trimWhitespaces` does. */
@@ -77,15 +86,53 @@ function isIndex(segment: string): boolean {
   return /^\d+$/.test(segment)
 }
 
-/** Assign `value` at `segments` inside `target`, creating containers as needed. */
-function assign(target: Record<string, unknown>, segments: string[], value: unknown): void {
-  let cursor: Record<string, unknown> | unknown[] = target
+type Container = Record<string, unknown> | unknown[]
+
+function isContainer(value: unknown): value is Container {
+  return typeof value === 'object' && value !== null
+}
+
+/** `{ '0': a, '1': b }` from `[a, b]`, holes left out — what `qs` produces on overflow. */
+function arrayToObject(array: unknown[]): Record<string, unknown> {
+  const object: Record<string, unknown> = {}
+  array.forEach((item, index) => {
+    object[String(index)] = item
+  })
+  return object
+}
+
+/**
+ * Assign `value` at `segments` inside `target`, creating containers as needed.
+ *
+ * An explicit index at or above `arrayLimit` never addresses an array: the
+ * container becomes (or is converted into) an object keyed by that index,
+ * as `qs` does. Without it, `ids[100000000]=1` allocates a sparse array whose
+ * iteration or serialisation blocks the event loop for seconds. Appends
+ * (`tags[]`, a repeated key) stay arrays — each one costs a parameter, so
+ * `parameterLimit` already bounds them, and a long checkbox group keeps the
+ * shape its handler expects (`qs` turns those into objects past the limit).
+ */
+function assign(
+  target: Record<string, unknown>,
+  segments: string[],
+  value: unknown,
+  arrayLimit: number,
+): void {
+  let cursor: Container = target
+  // Swaps `cursor` inside its parent when an array has to become an object.
+  let replace: (next: Container) => void = () => {}
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i] ?? ''
     const last = i === segments.length - 1
 
     if (FORBIDDEN_KEYS.has(segment)) return
 
+    if (Array.isArray(cursor) && isIndex(segment) && Number(segment) >= arrayLimit) {
+      const converted = arrayToObject(cursor)
+      replace(converted)
+      cursor = converted
+    }
+
     if (last) {
       if (segment === '') {
         // `tags[]` — append.
@@ -109,24 +156,31 @@ function assign(target: Record<string, unknown>, segments: string[], value: unkn
     }
 
     const nextSegment = segments[i + 1] ?? ''
-    const wantsArray = nextSegment === '' || isIndex(nextSegment)
+    const wantsArray =
+      nextSegment === '' || (isIndex(nextSegment) && Number(nextSegment) < arrayLimit)
 
     if (Array.isArray(cursor)) {
       if (!isIndex(segment)) return
+      const array: unknown[] = cursor
       const index = Number(segment)
-      const existing = cursor[index]
-      if (existing === undefined || typeof existing !== 'object' || existing === null) {
-        cursor[index] = wantsArray ? [] : {}
+      const existing: unknown = array[index]
+      const child: Container = isContainer(existing) ? existing : wantsArray ? [] : {}
+      array[index] = child
+      replace = (next) => {
+        array[index] = next
       }
-      cursor = cursor[index] as Record<string, unknown> | unknown[]
+      cursor = child
       continue
     }
 
-    const existing = cursor[segment]
-    if (existing === undefined || typeof existing !== 'object' || existing === null) {
-      cursor[segment] = wantsArray ? [] : {}
+    const object: Record<string, unknown> = cursor
+    const existing: unknown = object[segment]
+    const child: Container = isContainer(existing) ? existing : wantsArray ? [] : {}
+    object[segment] = child
+    replace = (next) => {
+      object[segment] = next
     }
-    cursor = cursor[segment] as Record<string, unknown> | unknown[]
+    cursor = child
   }
 }
 
@@ -153,27 +207,43 @@ export function parseQueryString(
   body: string,
   options: QsParseOptions = {},
 ): Record<string, unknown> {
-  const depth = options.depth ?? DEFAULT_DEPTH
+  if (!body) return {}
   const parameterLimit = options.parameterLimit ?? DEFAULT_PARAMETER_LIMIT
-  const result: Record<string, unknown> = {}
-  if (!body) return result
-
-  const pairs = body.split('&')
-  let seen = 0
-  for (const pair of pairs) {
+  const fields: Array<{ name: string; value: string }> = []
+  for (const pair of body.split('&')) {
     if (!pair) continue
-    if (++seen > parameterLimit) break
-
+    // Nothing past the limit is even decoded.
+    if (fields.length >= parameterLimit) break
     const eqIdx = pair.indexOf('=')
     const rawKey = eqIdx === -1 ? pair : pair.slice(0, eqIdx)
     const rawValue = eqIdx === -1 ? '' : pair.slice(eqIdx + 1)
+    fields.push({ name: decodeFormComponent(rawKey), value: decodeFormComponent(rawValue) })
+  }
+  return parseFormFields(fields, options)
+}
 
-    const key = decodeFormComponent(rawKey)
-    let value: unknown = decodeFormComponent(rawValue)
+/**
+ * Nest form fields that arrive as decoded name/value pairs — a multipart
+ * body's text parts — with the key grammar and the guards of a urlencoded
+ * body. A `<select multiple name="tags[]">` keeps every value, and
+ * `user[name]` nests, whether or not the form also carries a file input.
+ */
+export function parseFormFields(
+  fields: Iterable<{ name: string; value: string }>,
+  options: QsParseOptions = {},
+): Record<string, unknown> {
+  const depth = options.depth ?? DEFAULT_DEPTH
+  const parameterLimit = options.parameterLimit ?? DEFAULT_PARAMETER_LIMIT
+  const arrayLimit = options.arrayLimit ?? DEFAULT_ARRAY_LIMIT
+  const result: Record<string, unknown> = {}
+
+  let seen = 0
+  for (const field of fields) {
+    if (++seen > parameterLimit) break
+    let value: unknown = field.value
     if (options.trimWhitespaces && typeof value === 'string') value = value.trim()
     if (options.convertEmptyStringsToNull && value === '') value = null
-
-    assign(result, splitKey(key, depth, options.allowDots ?? true), value)
+    assign(result, splitKey(field.name, depth, options.allowDots ?? true), value, arrayLimit)
   }
   return result
 }