@c9up/ream 0.2.28 → 0.2.30

package/src/server/nativeLimits.ts

@@ -0,0 +1,111 @@
+/**
+ * The limits the native server applies at the socket, read from the
+ * application's configuration.
+ *
+ * - Body limits come from `config/bodyparser.ts`: the native server enforces
+ *   each section's `limit` WHILE reading the body, so nothing past it is ever
+ *   buffered. The request still reaches routing, without its body and marked
+ *   `bodyTooLarge`; reading the body then throws the 413 the body parser
+ *   raises. The body parser keeps its own check; the two read one config.
+ * - Timeouts and the connection cap come from `config/app.ts` → `http`, where
+ *   an AdonisJS app sets `headersTimeout`, `requestTimeout` and
+ *   `keepAliveTimeout` for Node's server. `maxConnections` has no AdonisJS
+ *   option (Node's `server.maxConnections` is left unbounded there); it is a
+ *   deliberate DoS bound, and past it new clients wait in the listen backlog.
+ *
+ * Why the body limits are applied natively at all (NAPI constraint): the
+ * native server hands JS a request whose body is already read, where AdonisJS
+ * leaves the body in Node's stream until the parser pulls it. Without a limit
+ * at the read, every body is buffered before any JS-side limit can apply.
+ */
+
+import type { BodyParserConfig } from '../bodyparser/BodyParserMiddleware.js'
+import { parseSize } from '../bodyparser/parseSize.js'
+import { ReamError } from '../errors/ReamError.js'
+
+/** One body-parser section as the native server takes it (bytes). */
+export interface NativeBodyLimit {
+  limit?: number
+  types?: string[]
+}
+
+/**
+ * The multipart section, with the part counts the native parser enforces
+ * while it parses: it stops at the first field or file past its bound.
+ */
+export interface NativeMultipartLimit extends NativeBodyLimit {
+  maxFields?: number
+  maxFiles?: number
+}
+
+/** Body limits per body-parser section; an omitted section keeps its default. */
+export interface NativeBodyLimits {
+  json?: NativeBodyLimit
+  form?: NativeBodyLimit
+  raw?: NativeBodyLimit
+  multipart?: NativeMultipartLimit
+}
+
+/** Timeouts in milliseconds (`0` disables one) and the connection cap (`0` = unbounded). */
+export interface NativeConnectionConfig {
+  headersTimeout?: number
+  requestTimeout?: number
+  keepAliveTimeout?: number
+  maxConnections?: number
+}
+
+const SECTIONS = ['json', 'form', 'raw', 'multipart'] as const
+
+/** Translate `config/bodyparser.ts` into the native server's body limits. */
+export function nativeBodyLimits(config: BodyParserConfig): NativeBodyLimits {
+  const limits: NativeBodyLimits = {}
+  for (const section of SECTIONS) {
+    const given = config[section]
+    if (!given) continue
+    const native: NativeBodyLimit = {}
+    if (given.limit !== undefined) native.limit = parseSize(given.limit)
+    if (given.types !== undefined) native.types = [...given.types]
+    limits[section] = native
+  }
+  const multipart = config.multipart
+  if (multipart) {
+    limits.multipart = {
+      ...limits.multipart,
+      ...(multipart.maxFields !== undefined && { maxFields: multipart.maxFields }),
+      ...(multipart.maxFiles !== undefined && { maxFiles: multipart.maxFiles }),
+    }
+  }
+  return limits
+}
+
+const CONNECTION_KEYS = [
+  'headersTimeout',
+  'requestTimeout',
+  'keepAliveTimeout',
+  'maxConnections',
+] as const
+
+const MAX_U32 = 2 ** 32 - 1
+
+/**
+ * Pick the connection settings out of the `http` block of `config/app.ts`.
+ * Throws on a value that is not a whole number of milliseconds (or
+ * connections) the native server can hold, rather than letting it wrap.
+ */
+export function nativeConnectionConfig(http: unknown): NativeConnectionConfig {
+  const config: NativeConnectionConfig = {}
+  if (typeof http !== 'object' || http === null) return config
+  for (const key of CONNECTION_KEYS) {
+    const value: unknown = Reflect.get(http, key)
+    if (value === undefined) continue
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > MAX_U32) {
+      throw new ReamError(
+        'E_IGNITOR_INVALID_HTTP_CONFIG',
+        `\`http.${key}\` must be a whole number between 0 and ${MAX_U32}, received ${String(value)}.`,
+        { hint: 'Timeouts are in milliseconds; 0 disables the bound.' },
+      )
+    }
+    config[key] = value
+  }
+  return config
+}

package/src/session/Session.ts

@@ -10,6 +10,7 @@
  * Backed by pluggable drivers (cookie, memory, redis).
  */
 
+import type { CookieOptions } from '../http/Response.js'
 import type { SessionRedisClientSource } from './drivers/RedisDriver.js'
 import {
   E_SESSION_NOT_READY,
@@ -154,8 +155,23 @@ export interface SessionConfig {
   client?: SessionRedisClientSource
   /** `redis` driver only — key prefix. Defaults to `ream:session:`. */
   prefix?: string
+  /**
+   * Attributes of the session cookie, for every store. Defaults:
+   * `{ path: '/', httpOnly: true, sameSite: 'lax' }`, and `secure` on when
+   * `NODE_ENV` is production. Its lifetime comes from {@link age} and
+   * {@link clearWithBrowser}, not from here. `httpOnly: false` is refused: a
+   * script able to read the session cookie is what turns an XSS into an
+   * account takeover.
+   */
+  cookie?: SessionCookieOptions
 }
 
+/** The session cookie attributes an application may set. */
+export type SessionCookieOptions = Pick<
+  CookieOptions,
+  'path' | 'httpOnly' | 'secure' | 'sameSite' | 'domain' | 'partitioned' | 'priority'
+>
+
 /**
  * Generate a fresh session ID. Format mirrors AdonisJS / express-session —
  * 32 bytes of base64url entropy (~256 bits). Defined here so `regenerate()`
@@ -272,19 +288,28 @@ export class Session {
     // The store is untyped by nature, so `T` is the CALLER's claim about what
     // it put there — one assertion from `unknown`, which is what `T` means
     // here. Going through `any` first widened nothing and hid the intent.
-    if (key in this.#data) return this.#data[key] as T
+    // OWN keys only: `in` walked the prototype, so an empty session answered
+    // `get('toString')` with a function and `has('constructor')` with true.
+    if (Object.hasOwn(this.#data, key)) return this.#data[key] as T
     return defaultValue as T
   }
 
   /** Set a session value. */
   put(key: string, value: unknown): void {
-    this.#data[key] = value
+    // Defined, not assigned: `put('__proto__', x)` stores a key like any
+    // other instead of replacing the session data's prototype.
+    Object.defineProperty(this.#data, key, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
     this.#dirty = true
   }
 
   /** Check if a key exists. */
   has(key: string): boolean {
-    return key in this.#data
+    return Object.hasOwn(this.#data, key)
   }
 
   /** Get all session data. */
@@ -488,7 +513,7 @@ export class Session {
   old<T = unknown>(key: string, defaultValue?: T): T {
     // Same contract as `get`: `T` is the caller's claim about a store that is
     // untyped by nature.
-    if (key in this.#previousFlash) return this.#previousFlash[key] as T
+    if (Object.hasOwn(this.#previousFlash, key)) return this.#previousFlash[key] as T
     return defaultValue as T
   }
 

package/src/session/SessionMiddleware.ts

@@ -10,15 +10,17 @@ import { readModuleConfig } from '../config/moduleConfig.js'
 import { currentNodeEnv } from '../env/nodeEnv.js'
 import { durationToSeconds } from '../helpers/duration.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import type { CookieOptions } from '../http/Response.js'
 import type { SessionConfigInput } from './config.js'
 import { CookieDriver } from './drivers/CookieDriver.js'
 import { DatabaseDriver, type SessionDbConnection } from './drivers/DatabaseDriver.js'
 import { FileDriver } from './drivers/FileDriver.js'
 import { MemoryDriver } from './drivers/MemoryDriver.js'
 import { RedisDriver } from './drivers/RedisDriver.js'
+import { E_SESSION_COOKIE_NOT_HTTP_ONLY, E_SESSION_STORE_NOT_CONFIGURED } from './errors.js'
 import { quasarConnection } from './quasar.js'
 import { ReadOnlyValuesStore, type ValuePath } from './ReadOnlyValuesStore.js'
-import type { SessionDriver } from './Session.js'
+import type { SessionCookieOptions, SessionDriver } from './Session.js'
 import { Session } from './Session.js'
 
 interface ResolvedSessionConfig {
@@ -27,6 +29,7 @@ interface ResolvedSessionConfig {
   maxAge: number
   clearWithBrowser: boolean
   rolling: boolean
+  cookie: SessionCookieOptions
 }
 
 /** Duck-typed check for a connection the database store can drive. */
@@ -61,8 +64,15 @@ export default class SessionMiddleware {
     // `{ store: 'redis', stores: { redis: { driver: 'redis' } } }` works.
     const selected = config?.store ?? config?.driver
     const named = selected ? config?.stores?.[selected] : undefined
+    // No implicit store, in any environment — AdonisJS' session config
+    // refuses one without `store` too. The memory store lives in one process
+    // and is bounded: a restart, a second replica, or enough anonymous
+    // requests signs every user out, so it is used only when it is chosen
+    // (`store: 'memory'`).
+    if (!selected) throw new E_SESSION_STORE_NOT_CONFIGURED()
+    if (config?.cookie?.httpOnly === false) throw new E_SESSION_COOKIE_NOT_HTTP_ONLY()
     this.#config = {
-      driver: named?.driver ?? selected ?? 'memory',
+      driver: named?.driver ?? selected,
       cookieName: config?.cookieName ?? 'ream_session',
       // `age` is the AdonisJS key and accepts a duration string.
       maxAge:
@@ -71,6 +81,7 @@ export default class SessionMiddleware {
           : (config?.maxAge ?? 7200),
       clearWithBrowser: config?.clearWithBrowser ?? false,
       rolling: config?.rolling ?? false,
+      cookie: { ...config?.cookie },
     }
 
     if (this.#config.driver === 'cookie') {
@@ -189,11 +200,8 @@ export default class SessionMiddleware {
           // Already encrypted by the cookie driver; packing it again would
           // only make the cookie bigger and change nothing.
           encode: false,
+          ...this.#cookieAttributes(isProduction),
           maxAge: this.#config.clearWithBrowser ? undefined : Math.ceil(remaining / 1000),
-          path: '/',
-          httpOnly: true,
-          sameSite: 'lax',
-          secure: isProduction,
         })
       }
       return
@@ -242,14 +250,26 @@ export default class SessionMiddleware {
       // read, before any store lookup, and that an id from another deployment
       // (a different APP_KEY) cannot be presented here.
       ctx.response.cookie(cookieName, session.sessionId, {
+        ...this.#cookieAttributes(isProduction),
         maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
-        path: '/',
-        httpOnly: true,
-        sameSite: 'lax',
-        secure: isProduction,
       })
     }
   }
+
+  /**
+   * The session cookie's attributes: the configured `cookie` over the
+   * defaults. `secure` follows the environment unless the config sets it.
+   */
+  #cookieAttributes(isProduction: boolean): CookieOptions {
+    const configured = this.#config.cookie
+    return {
+      path: '/',
+      sameSite: 'lax',
+      ...configured,
+      httpOnly: true,
+      secure: configured.secure ?? isProduction,
+    }
+  }
 }
 
 function generateSessionId(): string {

package/src/session/config.ts

@@ -13,6 +13,7 @@
  *   })
  */
 
+import { E_SESSION_STORE_NOT_CONFIGURED } from './errors.js'
 import type { SessionConfig } from './Session.js'
 
 /** What a session config file may declare. */
@@ -24,6 +25,12 @@ export type SessionConfigInput = SessionConfig & {
   secret?: string
 }
 
+/**
+ * Validate and return a session config. A config without `store` (or its
+ * older spelling `driver`) is refused here, at load time, as AdonisJS'
+ * `defineConfig` refuses it: there is no implicit store.
+ */
 export function defineConfig(config: SessionConfigInput): SessionConfigInput {
+  if (!config.store && !config.driver) throw new E_SESSION_STORE_NOT_CONFIGURED()
   return config
 }

package/src/session/drivers/MemoryDriver.ts

@@ -3,14 +3,25 @@ import type { SessionDriverWithTagging, TaggedSession } from '../Session.js'
 /** Sweep expired entries once the store reaches this size. */
 const SWEEP_THRESHOLD = 1000
 
+/**
+ * At most one sweep per this many milliseconds.
+ *
+ * A sweep walks the whole store. Run on every write past the threshold, a
+ * flood of anonymous requests turned each write into a 10 000-entry scan —
+ * quadratic, and 20 000 writes took seconds. Between two sweeps the cap below
+ * still bounds the store, and a read drops the expired entry it lands on.
+ */
+const SWEEP_INTERVAL_MS = 1000
+
 /**
  * Hard cap on live sessions.
  *
  * The sweep alone only removes EXPIRED entries, so within the TTL window
  * nothing bounded growth: anyone able to request a page could mint sessions
  * until the process ran out of memory, without ever logging in. Past the cap
- * the oldest sessions are dropped — a bounded store that forgets is strictly
- * better than an unbounded one that dies.
+ * the least recently used sessions are dropped (a write, an update or a
+ * touch moves a session to the back of the line) — a bounded store that
+ * forgets is strictly better than an unbounded one that dies.
  */
 const DEFAULT_MAX_ENTRIES = 10_000
 
@@ -24,6 +35,8 @@ export class MemoryDriver implements SessionDriverWithTagging {
   /** user id → the sessions tagged with it. */
   #tags: Map<string, Set<string>> = new Map()
   readonly #maxEntries: number
+  /** When the last sweep ran, epoch milliseconds. */
+  #lastSweep = 0
 
   constructor(options: MemoryDriverOptions = {}) {
     this.#maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES)
@@ -39,8 +52,9 @@ export class MemoryDriver implements SessionDriverWithTagging {
   }
 
   async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
-    if (this.#store.size >= SWEEP_THRESHOLD) {
-      const now = Date.now()
+    const now = Date.now()
+    if (this.#store.size >= SWEEP_THRESHOLD && now - this.#lastSweep >= SWEEP_INTERVAL_MS) {
+      this.#lastSweep = now
       for (const [id, entry] of this.#store) {
         if (entry.expiresAt < now) this.#store.delete(id)
       }
@@ -78,9 +92,14 @@ export class MemoryDriver implements SessionDriverWithTagging {
 
   async touch(sessionId: string, ttl: number): Promise<void> {
     const entry = this.#store.get(sessionId)
-    if (entry) {
-      entry.expiresAt = Date.now() + ttl * 1000
-    }
+    if (!entry || entry.expiresAt < Date.now()) return
+    // Re-inserted, not updated in place: eviction drops the head of the map,
+    // so a session in use has to move to the tail. Updated in place, a
+    // signed-in user who keeps browsing stayed first in line, and ten
+    // thousand anonymous requests evicted them.
+    entry.expiresAt = Date.now() + ttl * 1000
+    this.#store.delete(sessionId)
+    this.#store.set(sessionId, entry)
   }
 
   async tag(sessionId: string, userId: string | number): Promise<void> {

package/src/session/errors.ts

@@ -54,3 +54,34 @@ export class E_SESSION_TAGGING_NOT_SUPPORTED extends Exception {
     )
   }
 }
+
+/**
+ * A session config without a store (AdonisJS raises "Missing store" for the
+ * same config). There is no implicit fallback: the memory store is per
+ * process and bounded — a restart, a second replica or enough anonymous
+ * traffic signs every user out — so it is only used when it is chosen.
+ */
+export class E_SESSION_STORE_NOT_CONFIGURED extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_STORE_NOT_CONFIGURED'
+
+  constructor() {
+    super(
+      "No session store is configured. Set `store` in config/session.ts (redis, database, file or cookie), or `store: 'memory'` for sessions kept in this process only (tests, a single development instance).",
+      { status: 500, code: 'E_SESSION_STORE_NOT_CONFIGURED' },
+    )
+  }
+}
+
+/** `cookie.httpOnly: false` — the session id would be readable by any script on the page. */
+export class E_SESSION_COOKIE_NOT_HTTP_ONLY extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_COOKIE_NOT_HTTP_ONLY'
+
+  constructor() {
+    super(
+      'The session cookie must be httpOnly: a script able to read it turns any XSS into an account takeover. Remove `cookie.httpOnly: false` from the session config.',
+      { status: 500, code: 'E_SESSION_COOKIE_NOT_HTTP_ONLY' },
+    )
+  }
+}

package/src/session/templateTags.ts

@@ -1,3 +1,5 @@
+import { ReamError } from '../errors/ReamError.js'
+
 /**
  * The flash-message tags AdonisJS's session publishes to templates.
  *
@@ -122,3 +124,58 @@ export function registerSessionTemplateTags(engine: TemplateTagEngine): void {
     },
   })
 }
+
+/** Loads the template engine package. Swappable so a test needs no engine. */
+export type EnginePackageLoader = () => Promise<unknown>
+
+const loadInker: EnginePackageLoader = () => {
+  // Built rather than written inline: inker is an OPTIONAL peer, and a literal
+  // `import('@c9up/inker')` makes a bundler resolve it at build time for an
+  // application that never installed it. Computed, it only runs behind the
+  // `usingInker` flag.
+  const specifier = '@c9up/inker'
+  return import(/* @vite-ignore */ specifier)
+}
+
+function unusable(detail: string): ReamError {
+  return new ReamError(
+    'E_SESSION_TEMPLATE_ENGINE_UNUSABLE',
+    `The template engine is installed but the session tags cannot be registered: ${detail}`,
+    {
+      hint: '`@c9up/inker` must default-export its plugin registrar (`inker.use(plugin)`), whose plugins receive an engine with `registerTag()`.',
+    },
+  )
+}
+
+/**
+ * Publish the session tags into the template engine, the way AdonisJS's
+ * session does with Edge: through the engine package's MODULE SINGLETON
+ * (`inker.use(plugin)`), guarded by the host's `usingInker` flag — never by
+ * resolving a container binding. `use()` queues the plugin, and the engine
+ * runs it before its next render, whenever the engine was built.
+ *
+ * Returns whether the tags were handed over. A registrar or an engine of the
+ * wrong shape is an error, not a skip: a template using `@flashMessage`
+ * would otherwise render it as plain text with no warning.
+ */
+export async function installSessionTemplateTags(
+  usingInker: boolean,
+  load: EnginePackageLoader = loadInker,
+): Promise<boolean> {
+  if (!usingInker) return false
+  const module: unknown = await load()
+  const registrar =
+    typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : undefined
+  const use = Reflect.get(Object(registrar), 'use')
+  if (typeof use !== 'function') throw unusable('its default export has no use()')
+  use.call(registrar, (engine: unknown) => {
+    const register = Reflect.get(Object(engine), 'registerTag')
+    if (typeof register !== 'function') throw unusable('the engine has no registerTag()')
+    registerSessionTemplateTags({
+      registerTag: (tag) => {
+        register.call(engine, tag)
+      },
+    })
+  })
+  return true
+}

package/src/storage/StaticMiddleware.ts

@@ -147,11 +147,18 @@ export class StaticMiddleware {
     const method = ctx.request.method()
     if (method !== 'GET' && method !== 'HEAD') return next()
 
-    const reqPath = ctx.request.path()
+    // Outside the prefix the request is none of this middleware's business —
+    // not even a dot-file refusal, or `{ prefix: '/static', dotFiles: 'deny' }`
+    // answers 403 to an application route such as `/.well-known/...`.
+    const reqPath = this.#withinPrefix(ctx.request.path())
+    if (reqPath === null) return next()
 
     // A dotfile under `deny` is answered, not passed on: falling through would
-    // leak its existence through whatever the router answers next.
-    if (this.#dotFiles === 'deny' && this.#hasDotSegment(reqPath)) {
+    // leak its existence through whatever the router answers next. The check
+    // runs on the DECODED path — the name that would be opened — or `/%2eenv`
+    // reaches `.env`. A path that does not decode is checked raw; it is never
+    // served anyway.
+    if (this.#dotFiles === 'deny' && this.#hasDotSegment(decodePath(reqPath) ?? reqPath)) {
       ctx.response.status(403).send('Forbidden')
       return
     }
@@ -324,36 +331,37 @@ export class StaticMiddleware {
    * from the descriptor: what gets served is then the same file that passed the
    * checks, which a path re-read after the fact cannot promise.
    */
+  /**
+   * The request path below the prefix, or `null` when it lies outside it.
+   * Match only when the prefix is followed by `/` or end-of-path — otherwise
+   * `/staticx/foo.js` would be intercepted when the configured prefix is
+   * `/static`, hijacking unrelated routes.
+   */
+  #withinPrefix(reqPath: string): string | null {
+    if (this.#prefix === '') return reqPath
+    if (!(reqPath === this.#prefix || reqPath.startsWith(`${this.#prefix}/`))) return null
+    return reqPath.slice(this.#prefix.length) || '/'
+  }
+
+  /** `reqPath` is already relative to the prefix ({@link #withinPrefix}). */
   async #openServableFile(
     reqPath: string,
   ): Promise<{ handle: FileHandle; filePath: string; stat: fs.Stats } | null> {
-    if (this.#prefix !== '') {
-      // Match only when the prefix is followed by `/` or end-of-path —
-      // otherwise `/staticx/foo.js` would be intercepted when the configured
-      // prefix is `/static`, hijacking unrelated routes.
-      if (!(reqPath === this.#prefix || reqPath.startsWith(`${this.#prefix}/`))) return null
-      reqPath = reqPath.slice(this.#prefix.length) || '/'
-    }
-
-    if (this.#dotFiles === 'ignore' && this.#hasDotSegment(reqPath)) return null
-
-    // The candidates, in upstream's order: the path itself, then the path with
-    // each fallback extension, then the index files for a directory request.
-    //
-    // Percent-decoding happens BEFORE resolution on purpose: `%2e%2e%2f` is
-    // `../` and has to be normalised away by `path.resolve` like any other
-    // traversal, not carried through as an opaque segment. `decodeURIComponent`
-    // THROWS on a malformed sequence (a lone `%`), which would otherwise become
-    // a 500 on a request anyone can send.
-    let decoded: string
-    try {
-      decoded = decodeURIComponent(reqPath)
-    } catch {
-      return null
-    }
+    // Percent-decoding happens BEFORE any check and BEFORE resolution on
+    // purpose: the dot-file policy has to see the name that will be opened
+    // (`%2eenv` is `.env`), and `%2e%2e%2f` is `../`, which has to be
+    // normalised away by `path.resolve` like any other traversal, not carried
+    // through as an opaque segment. A malformed sequence (a lone `%`) is not
+    // servable.
+    const decoded = decodePath(reqPath)
+    if (decoded === null) return null
     // A NUL truncates the path in the syscall layer of some runtimes; Node
     // rejects it, but refusing here keeps the decision in one place.
     if (decoded.includes('\0')) return null
+    if (this.#dotFiles !== 'allow' && this.#hasDotSegment(decoded)) return null
+
+    // The candidates, in upstream's order: the path itself, then the path with
+    // each fallback extension, then the index files for a directory request.
     const relative = decoded.replace(/^\/+/, '')
     const candidates: string[] = []
     if (relative !== '') {
@@ -367,6 +375,8 @@ export class StaticMiddleware {
     }
 
     for (const candidate of candidates) {
+      // A configured index or extension can itself name a dot file.
+      if (this.#dotFiles !== 'allow' && this.#hasDotSegment(candidate)) continue
       const opened = await this.#openInRoot(candidate)
       if (opened) return opened
     }
@@ -426,6 +436,15 @@ export class StaticMiddleware {
   }
 }
 
+/** `decodeURIComponent` that answers `null` instead of throwing on a malformed sequence. */
+function decodePath(reqPath: string): string | null {
+  try {
+    return decodeURIComponent(reqPath)
+  } catch {
+    return null
+  }
+}
+
 /**
  * Static config with the defaults filled in — `@adonisjs/static`'s
  * `defineConfig`, value for value.

package/src/testing/ApiResponse.ts

@@ -78,7 +78,13 @@ export function partialMatch(actual: unknown, expected: unknown): boolean {
 
 /** Split a `Set-Cookie` header value into its individual cookie strings. */
 function splitSetCookie(setCookie: string): string[] {
-  return setCookie.split(/,(?=\s*[\w-]+=)/).map((c) => c.trim())
+  // One cookie per line, as the response parser stores them; a header folded
+  // with commas by another source is still split where a new `name=` starts.
+  return setCookie
+    .split('\n')
+    .flatMap((line) => line.split(/,(?=\s*[\w-]+=)/))
+    .map((c) => c.trim())
+    .filter((c) => c !== '')
 }
 
 /** A parsed response cookie — `name` + `value` plus any attributes present. */

package/src/testing/TestClient.ts

@@ -195,7 +195,7 @@ export class TestClient {
         m,
         p,
         { ...this.#headers, ...init.headers },
-        init.body.toString('utf8'),
+        init.body,
         init.timeoutMs,
       )
     }
@@ -288,7 +288,7 @@ async function sendRequest(
   method: string,
   path: string,
   headers: Dict,
-  body: string,
+  body: Buffer,
   timeoutMs?: number,
 ): Promise<TestResponse> {
   const { connect } = await import('node:net')
@@ -300,7 +300,10 @@ async function sendRequest(
         .map(([k, v]) => `${k}: ${v}`)
         .join('\r\n')
 
-      const contentLength = Buffer.byteLength(body, 'utf8')
+      // The body stays a Buffer end to end: a multipart upload of a PNG or a
+      // PDF is not valid UTF-8, and a round trip through a string replaced
+      // every such byte with U+FFFD before the server ever saw it.
+      const contentLength = body.length
 
       let request = `${method} ${path} HTTP/1.1\r\n`
       request += `Host: localhost:${port}\r\n`
@@ -312,9 +315,9 @@ async function sendRequest(
         request += `${headerLines}\r\n`
       }
       request += '\r\n'
-      request += body
 
       socket.write(request)
+      if (contentLength > 0) socket.write(body)
     })
 
     const chunks: Buffer[] = []
@@ -371,13 +374,19 @@ export function parseHttpResponse(raw: string | Buffer): TestResponse {
   const [, statusDigits] = statusLine.match(/HTTP\/\d+\.\d+ (\d+)/) ?? []
   const status = statusDigits === undefined ? 0 : Number.parseInt(statusDigits, 10)
 
+  // A repeated header is never overwritten. Set-Cookie lines are joined with
+  // `\n`, the way `Response.getHeaders()` hands them to the serializer: a
+  // cookie's `Expires` holds a comma, so a comma cannot separate two of them
+  // (RFC 6265 §3). Any other field is combined with `, ` (RFC 9110 §5.3).
   const headers: Dict = {}
   for (const line of lines.slice(1)) {
     const colonIdx = line.indexOf(':')
     if (colonIdx === -1) continue
     const key = line.slice(0, colonIdx).trim().toLowerCase()
     const value = line.slice(colonIdx + 1).trim()
-    headers[key] = value
+    const existing = headers[key]
+    if (existing === undefined) headers[key] = value
+    else headers[key] = `${existing}${key === 'set-cookie' ? '\n' : ', '}${value}`
   }
 
   // RFC 7230 §4.1: when Transfer-Encoding includes `chunked`, the message body

package/src/utils/Macroable.ts

@@ -27,12 +27,12 @@ export type MacroFn = (...args: unknown[]) => unknown
 /** A getter implementation — declare `this` in your callback to type the receiver. */
 export type GetterFn = () => unknown
 
-// biome-ignore lint/complexity/noStaticOnlyClass: eight classes extend this one to inherit macro()/getter(); it is a base class, not a namespace.
+// biome-ignore lint/complexity/noStaticOnlyClass: nine classes extend this one to inherit macro()/getter(); it is a base class, not a namespace.
 export class Macroable {
   /**
    * Attach a method to every instance of THIS class (AdonisJS `macro`).
    *
-   * `this.prototype`, not `Macroable.prototype`: eight classes extend this one,
+   * `this.prototype`, not `Macroable.prototype`: nine classes extend this one,
    * and defining on the base put every macro on all of them — a
    * `Response.macro('json', …)` also landed on `Request`, `Router` and
    * `HttpContext`, and two subclasses declaring the same name clobbered each