@c9up/ream 0.1.34 → 0.2.1

package/src/bodyparser/BodyParserMiddleware.ts

@@ -6,12 +6,19 @@
  * Configured via config/bodyparser.ts.
  */
 
+import { Exception } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import { hydrateMultipartPayload } from './MultipartFile.js'
 import { parseSize } from './parseSize.js'
 import { parseQueryString, type QsParseOptions } from './qsParse.js'
 
 export interface BodyParserConfig {
+  /**
+   * HTTP methods whose body is parsed at all. AdonisJS defaults to
+   * `['POST', 'PUT', 'PATCH', 'DELETE']` and returns early for anything else,
+   * so a GET that happens to carry a JSON content-type is left untouched.
+   */
+  allowedMethods?: string[]
   json?: {
     limit?: string // e.g. '1mb'
     types?: string[]
@@ -37,15 +44,21 @@ export interface BodyParserConfig {
   multipart?: {
     /** Total multipart body size cap (sum of all file sizes). Default: '20mb'. */
     limit?: string
-    /** Maximum number of files per request. Default: 20. */
+    /**
+     * 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
+     * thousand one-byte files pass. Kept as a DoS bound, at the same scale as
+     * `maxFields` so it never rejects an upload AdonisJS would have accepted.
+     */
     maxFiles?: number
+    /** Maximum number of form fields. AdonisJS default: 1000. */
     maxFields?: number
-    tmpDir?: string
     types?: string[]
   }
 }
 
 interface ResolvedBodyParserConfig {
+  allowedMethods: string[]
   json: Required<NonNullable<BodyParserConfig['json']>>
   form: Required<NonNullable<BodyParserConfig['form']>>
   raw: Required<NonNullable<BodyParserConfig['raw']>>
@@ -53,6 +66,9 @@ interface ResolvedBodyParserConfig {
 }
 
 const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
+  // AdonisJS define_config: allowedMethods. A body is parsed only for methods
+  // that are supposed to carry one.
+  allowedMethods: ['POST', 'PUT', 'PATCH', 'DELETE'],
   json: {
     limit: '1mb',
     types: ['application/json', 'application/vnd.api+json'],
@@ -73,9 +89,8 @@ const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
   },
   multipart: {
     limit: '20mb',
-    maxFiles: 20,
-    maxFields: 500,
-    tmpDir: '/tmp',
+    maxFiles: 1000,
+    maxFields: 1000,
     types: ['multipart/form-data'],
   },
 }
@@ -86,6 +101,7 @@ export default class BodyParserMiddleware {
   constructor(config?: BodyParserConfig) {
     assertNoEnabledFlag(config)
     this.#config = {
+      allowedMethods: config?.allowedMethods ?? DEFAULT_CONFIG.allowedMethods,
       json: { ...DEFAULT_CONFIG.json, ...config?.json },
       form: { ...DEFAULT_CONFIG.form, ...config?.form },
       raw: { ...DEFAULT_CONFIG.raw, ...config?.raw },
@@ -94,15 +110,28 @@ export default class BodyParserMiddleware {
   }
 
   async handle(ctx: HttpContext, next: () => Promise<void>) {
+    // Only methods that are supposed to carry a body get one parsed
+    // (AdonisJS `allowedMethods`). Comparison is case-sensitive on the
+    // canonical upper-case verb, as AdonisJS' `includes()` is.
+    if (!this.#config.allowedMethods.includes(ctx.request.method())) {
+      return next()
+    }
+
+    // Many clients send `content-length: 0` on a bodyless request, which the
+    // parsers below do not recognise as empty (AdonisJS returns early here for
+    // the same reason).
+    if (!ctx.request.hasBody()) {
+      return next()
+    }
+
     const contentType = ctx.request.header('content-type') ?? ''
     const rawBody = ctx.request.raw()
 
-    // Size check
+    // 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))) {
-      ctx.response.status(413).json({
-        error: { code: 'E_REQUEST_ENTITY_TOO_LARGE', message: 'Request body exceeds size limit' },
-      })
-      return
+      throw entityTooLarge('request entity too large')
     }
 
     // JSON
@@ -134,7 +163,7 @@ export default class BodyParserMiddleware {
     if (matchesType(contentType, this.#config.multipart.types)) {
       const payload = ctx.request.multipart()
       if (payload) {
-        if (this.#rejectMultipart(ctx, payload.files, payload.fields)) return
+        this.#assertMultipartWithinLimits(payload.files, payload.fields)
         const { fields, files } = hydrateMultipartPayload(payload)
         // Fingerprint each file's real type from its magic bytes BEFORE handlers
         // run, so `request.file(field, { extnames })` validates against the
@@ -155,44 +184,36 @@ export default class BodyParserMiddleware {
     return this.#config.raw.limit
   }
 
-  /** Returns true (and writes a 413/400) when the multipart payload exceeds configured limits. */
-  #rejectMultipart(
-    ctx: HttpContext,
-    files: Array<{ size: number }>,
-    fields: Array<unknown>,
-  ): boolean {
+  /**
+   * Throws when the multipart payload exceeds a configured limit.
+   *
+   * All three raise the same 413 `E_REQUEST_ENTITY_TOO_LARGE` AdonisJS raises
+   * for `maxFields` and for an oversized body — one code for "you sent too
+   * much", whichever dimension it was.
+   */
+  #assertMultipartWithinLimits(files: Array<{ size: number }>, fields: Array<unknown>): void {
     const cfg = this.#config.multipart
-    const maxBytes = parseSize(cfg.limit)
 
     if (fields.length > cfg.maxFields) {
-      ctx.response.status(400).json({
-        error: {
-          code: 'E_TOO_MANY_FIELDS',
-          message: `Upload exceeds maxFields (${cfg.maxFields})`,
-        },
-      })
-      return true
+      throw entityTooLarge('Fields length limit exceeded')
     }
 
     if (files.length > cfg.maxFiles) {
-      ctx.response.status(400).json({
-        error: { code: 'E_TOO_MANY_FILES', message: `Upload exceeds maxFiles (${cfg.maxFiles})` },
-      })
-      return true
+      throw entityTooLarge('Files length limit exceeded')
     }
 
     const totalBytes = files.reduce((sum, f) => sum + f.size, 0)
-    if (totalBytes > maxBytes) {
-      ctx.response.status(413).json({
-        error: { code: 'E_REQUEST_ENTITY_TOO_LARGE', message: 'Upload exceeds size limit' },
-      })
-      return true
+    if (totalBytes > parseSize(cfg.limit)) {
+      throw entityTooLarge('request entity too large')
     }
-
-    return false
   }
 }
 
+/** 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' })
+}
+
 /**
  * Whether a request's content-type is claimed by one of `types`.
  *
@@ -233,4 +254,17 @@ function assertNoEnabledFlag(config?: BodyParserConfig): void {
       )
     }
   }
+
+  // `multipart.tmpDir` was accepted and never read by anything: the Rust
+  // multipart parser hands the body over in memory, so no file is ever written
+  // to a temporary directory — an app pointing it at a volume was silently
+  // getting nothing. Saying so beats letting it keep believing.
+  const multipart: unknown = config.multipart
+  if (multipart !== null && typeof multipart === 'object' && 'tmpDir' in multipart) {
+    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)`.',
+    )
+  }
 }

package/src/bodyparser/MultipartFile.ts

@@ -19,11 +19,70 @@ export class MultipartFile {
   readonly clientName: string
 
   /**
-   * MIME type from the Content-Type header. ATTACKER-CONTROLLED — never trust it
-   * for security decisions or as a response Content-Type. Prefer
-   * {@link detectedType}, which is fingerprinted from the file's magic bytes.
+   * The PRIMARY mime type — `image` for `image/png`. Pair it with
+   * {@link subtype}, as AdonisJS does.
+   *
+   * DERIVED FROM THE MAGIC BYTES when they can be read, and only from the
+   * Content-Type header when they cannot — upstream's precedence, and the one
+   * that matters: the header is written by the client, so a `.exe` announced as
+   * `image/png` would otherwise sail through a mime allowlist. A renamed file
+   * reports what it actually is.
+   *
+   * BREAKING as of 0.2.0: it used to hold the whole `image/png`. TypeScript
+   * cannot catch a comparison against a full mime string — `file.type ===
+   * 'image/png'` still compiles and simply never matches. Use {@link mime}.
    */
-  readonly type: string
+  get type(): string | undefined {
+    return this.#mimeParts()[0]
+  }
+
+  /** The mime SUBTYPE — `png` for `image/png`. Same source as {@link type}. */
+  get subtype(): string | undefined {
+    return this.#mimeParts()[1]
+  }
+
+  /**
+   * The full mime to validate against — `image/png`.
+   *
+   * What an allowlist wants, and the reason this exists: splitting the mime for
+   * upstream parity left every caller re-joining it by hand, and a caller that
+   * forgot got a filter that silently matched nothing. Same trustworthy source
+   * as {@link type}.
+   */
+  get mime(): string | undefined {
+    const [type, subtype] = this.#mimeParts()
+    if (!type) return undefined
+    return subtype ? `${type}/${subtype}` : type
+  }
+
+  /** Split the trustworthy mime once, detected bytes first, header second. */
+  #mimeParts(): [string | undefined, string | undefined] {
+    const source = this.#detected?.mime ?? this.#headerMime
+    if (!source) return [undefined, undefined]
+    const [type, subtype] = source.split(';')[0].trim().split('/')
+    return [type || undefined, subtype || undefined]
+  }
+
+  /**
+   * The part's headers.
+   *
+   * NAMED CONSTRAINT — Rust's multipart parser forwards only the part's
+   * content-type across the NAPI boundary today, so this carries that one
+   * header rather than every header the client sent.
+   */
+  readonly headers: Record<string, string>
+
+  /** Always true. Lets a value be told apart from a plain form field. */
+  readonly isMultipartFile = true as const
+
+  /** Where the file is in its life: idle, consumed, or moved to disk. */
+  state: 'idle' | 'streaming' | 'consumed' | 'moved' = 'consumed'
+
+  /** Absolute path the file was moved to, once it has been. */
+  filePath?: string
+
+  /** The name it was written under, once it has been moved. */
+  fileName?: string
 
   /** File size in bytes. */
   readonly size: number
@@ -43,6 +102,12 @@ export class MultipartFile {
   /** Extension derived from the (attacker-controlled) client filename. */
   #clientExtname: string
 
+  /** Rules set through `sizeLimit` / `allowedExtensions`, used by a bare `validate()`. */
+  #validationOptions: FileValidationOptions = {}
+
+  /** The Content-Type the client sent — attacker-controlled, the fallback only. */
+  readonly #headerMime: string
+
   /** Magic-byte fingerprint — set by {@link detectType}; absent for content `file-type` can't detect (text: txt/csv/svg/json). */
   #detected?: { ext: string; mime: string }
 
@@ -54,7 +119,8 @@ export class MultipartFile {
   }) {
     this.fieldName = options.fieldName
     this.clientName = options.clientName
-    this.type = options.type
+    this.headers = { 'content-type': options.type }
+    this.#headerMime = options.type
     this.content = options.content
     this.size = options.content.length
     const segments = options.clientName.split('.')
@@ -91,8 +157,37 @@ export class MultipartFile {
     return this.#detected?.ext ?? this.#clientExtname
   }
 
-  /** Validate file against size and extension rules. */
-  validate(options: FileValidationOptions): boolean {
+  /** The size ceiling set through {@link sizeLimit}, if any. */
+  get sizeLimit(): number | string | undefined {
+    return this.#validationOptions.size
+  }
+
+  set sizeLimit(limit: number | string | undefined) {
+    this.#validationOptions.size = typeof limit === 'number' ? String(limit) : limit
+  }
+
+  /** The extension allowlist set through {@link allowedExtensions}, if any. */
+  get allowedExtensions(): string[] | undefined {
+    return this.#validationOptions.extnames
+  }
+
+  set allowedExtensions(extensions: string[] | undefined) {
+    this.#validationOptions.extnames = extensions
+  }
+
+  /** Whether validation turned anything up. The inverse of {@link isValid}. */
+  get hasErrors(): boolean {
+    return this.errors.length > 0
+  }
+
+  /**
+   * Validate the file against size and extension rules.
+   *
+   * The argument is optional: called bare it uses whatever was set through
+   * {@link sizeLimit} and {@link allowedExtensions}, which is how AdonisJS
+   * spells it.
+   */
+  validate(options: FileValidationOptions = this.#validationOptions): boolean {
     if (options.size) {
       const maxBytes = parseFileSize(options.size)
       if (this.size > maxBytes) {
@@ -145,10 +240,60 @@ export class MultipartFile {
     }
     const filePath = join(directory, fileName)
     writeFileSync(filePath, this.content)
-    this.#moved = true
+    this.markAsMoved(fileName, filePath)
     return filePath
   }
 
+  /**
+   * Write the file into `location` (AdonisJS `move`).
+   *
+   * NAMED DEVIATION — upstream renames a temporary file it streamed to disk;
+   * Ream holds the bytes in memory (`multipart.tmpDir` is refused at
+   * 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.
+   */
+  async move(location: string, options?: { name?: string; overwrite?: boolean }): Promise<void> {
+    const { mkdir, writeFile, access } = await import('node:fs/promises')
+    const { join } = await import('node:path')
+
+    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)}`,
+      )
+    }
+
+    const filePath = join(location, name)
+    if (options?.overwrite === false) {
+      const exists = await access(filePath).then(
+        () => true,
+        () => false,
+      )
+      if (exists) {
+        throw new Error(
+          `"${name}" already exists at "${location}". Set "overwrite = true" to overwrite it`,
+        )
+      }
+    }
+
+    await mkdir(location, { recursive: true })
+    await writeFile(filePath, this.content)
+    this.markAsMoved(name, filePath)
+  }
+
+  /** Record that the file now lives on disk. */
+  markAsMoved(fileName: string, filePath: string): void {
+    this.fileName = fileName
+    this.filePath = filePath
+    this.state = 'moved'
+    this.#moved = true
+  }
+
   get isMoved(): boolean {
     return this.#moved
   }

package/src/console/BaseCommand.ts

@@ -112,7 +112,7 @@ export abstract class BaseCommand {
 
   /**
    * The error thrown by `prepare` / `interact` / `run`, assigned before
-   * `completed()` runs so the hook can inspect it (Console parity).
+   * `completed()` runs so the hook can inspect it.
    */
   error?: unknown
 
@@ -124,6 +124,13 @@ export abstract class BaseCommand {
    * `run`, then `completed` — which runs even when one of the earlier stages
    * threw. Returning `true` from `completed()` marks the error handled, so the
    * kernel stops propagating it.
+   *
+   * A SUPERSET, not parity: AdonisJS carried these three through ace 13 and
+   * dropped them in ace 14, whose command lifecycle is `hydrate()` then
+   * `run()` — both of which {@link hydrate} and {@link run} match exactly.
+   * They are kept because a `completed()` that runs even after a failure is
+   * the only place a command can clean up after itself, and a command written
+   * against either lifecycle works here.
    */
   // Parameters are allowed: the container injects them (`@inject()` on a
   // lifecycle method), and a no-arg signature rejects those commands.

package/src/console/Kernel.ts

@@ -268,6 +268,24 @@ export class Kernel {
     return this.#binaryName
   }
 
+  /**
+   * A named `true`, for a flag listener that wants to stop the run (Console
+   * `kernel.shortcircuit`).
+   *
+   * A listener returning a bare `true` reads like a bug at the call site;
+   * `return kernel.shortcircuit()` says what the boolean means:
+   *
+   * ```ts
+   * kernel.on('version', (_c, kernel) => {
+   *   console.log(version)
+   *   return kernel.shortcircuit()
+   * })
+   * ```
+   */
+  shortcircuit(): boolean {
+    return true
+  }
+
   /**
    * Declare a flag every command accepts (Console `kernel.defineFlag`).
    *

package/src/directories.ts

@@ -0,0 +1,81 @@
+/**
+ * The conventional directory layout, as `@adonisjs/application` exports it.
+ *
+ * Every path helper on {@link Application} reads this map, so an app that moves
+ * a directory declares it once in `reamrc.ts` and every helper follows:
+ *
+ * ```ts
+ * export default defineConfig({
+ *   directories: { httpControllers: 'app/http/controllers' },
+ * })
+ * ```
+ */
+export interface DirectoriesNode {
+  [key: string]: string
+  config: string
+  commands: string
+  contracts: string
+  public: string
+  providers: string
+  languageFiles: string
+  migrations: string
+  seeders: string
+  factories: string
+  views: string
+  start: string
+  tmp: string
+  tests: string
+  httpControllers: string
+  models: string
+  services: string
+  exceptions: string
+  mailers: string
+  mails: string
+  middleware: string
+  policies: string
+  validators: string
+  events: string
+  listeners: string
+  transformers: string
+  stubs: string
+  generatedClient: string
+  generatedServer: string
+}
+
+/**
+ * Defaults, matching AdonisJS directory for directory.
+ *
+ * NAMED DEVIATION — the two generated directories are `.ream/*` where upstream
+ * writes `.adonisjs/*`. A dot-directory in the user's project is product
+ * identity, not layout.
+ */
+export const directories: DirectoriesNode = {
+  config: 'config',
+  commands: 'commands',
+  contracts: 'contracts',
+  public: 'public',
+  providers: 'providers',
+  languageFiles: 'resources/lang',
+  migrations: 'database/migrations',
+  seeders: 'database/seeders',
+  factories: 'database/factories',
+  views: 'resources/views',
+  start: 'start',
+  tmp: 'tmp',
+  tests: 'tests',
+  httpControllers: 'app/controllers',
+  models: 'app/models',
+  services: 'app/services',
+  exceptions: 'app/exceptions',
+  mailers: 'app/mailers',
+  mails: 'app/mails',
+  middleware: 'app/middleware',
+  policies: 'app/policies',
+  validators: 'app/validators',
+  events: 'app/events',
+  listeners: 'app/listeners',
+  transformers: 'app/transformers',
+  stubs: 'stubs',
+  generatedClient: '.ream/client',
+  generatedServer: '.ream/server',
+}