@c9up/ream 0.2.9 → 0.2.11

package/src/bodyparser/MultipartFile.ts

@@ -110,6 +110,8 @@ export class MultipartFile {
 
   /** 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 }
+  /** Whether the magic-byte pass has run, however it turned out. */
+  #detectionRan = false
 
   constructor(options: {
     fieldName: string
@@ -136,9 +138,22 @@ export class MultipartFile {
    * extension in force — same fallback AdonisJS uses.
    */
   async detectType(): Promise<void> {
-    const { fileTypeFromBuffer } = await import('file-type')
+    const { fileTypeFromBuffer, supportedExtensions } = await import('file-type')
+    detectableExtensions = supportedExtensions
     const result = await fileTypeFromBuffer(this.content)
     if (result) this.#detected = { ext: result.ext, mime: result.mime }
+    this.#detectionRan = true
+  }
+
+  /**
+   * Where {@link mime} and {@link extname} came from.
+   *
+   * `'detected'` means the bytes said so. `'claimed'` means they did not, and
+   * what is reported is the filename and the header the client sent — which
+   * the client chose.
+   */
+  get typeSource(): 'detected' | 'claimed' {
+    return this.#detected ? 'detected' : 'claimed'
   }
 
   /**
@@ -201,11 +216,35 @@ export class MultipartFile {
         this.errors.push(
           `Extension '${this.extname}' not allowed. Allowed: ${options.extnames.join(', ')}`,
         )
+      } else if (this.#claimsATypeItCannotBe(options.extnames)) {
+        // Every allowed format carries a signature, and none was found — so the
+        // bytes are definitively not one of them, whatever the name says. A
+        // shell script uploaded as `avatar.png` with `Content-Type: image/png`
+        // otherwise passes an image allowlist, because both halves of what was
+        // checked came from the client.
+        this.errors.push(
+          `Extension '${this.extname}' is claimed by the upload, not found in its content. ` +
+            `Every allowed format (${options.extnames.join(', ')}) has a signature, and this file carries none.`,
+        )
       }
     }
     return this.errors.length === 0
   }
 
+  /**
+   * Whether refusing this upload is warranted on the strength of the allowlist
+   * alone.
+   *
+   * Only when the magic-byte pass actually ran and found nothing, AND every
+   * allowed extension is one it would have recognised. For a list that allows
+   * `csv` or `txt`, finding nothing is the normal case and says nothing.
+   */
+  #claimsATypeItCannotBe(extnames: string[]): boolean {
+    if (this.#detected || !this.#detectionRan) return false
+    if (!detectableExtensions) return false
+    return extnames.every((extension) => detectableExtensions?.has(extension))
+  }
+
   get isValid(): boolean {
     return this.errors.length === 0
   }
@@ -363,3 +402,11 @@ export function hydrateMultipartPayload(payload: {
   )
   return { fields, files }
 }
+
+/**
+ * The extensions `file-type` can recognise, captured on the first detection.
+ *
+ * Module-level because it is a property of the library, not of a file, and
+ * because `validate()` is synchronous while reading it is not.
+ */
+let detectableExtensions: ReadonlySet<string> | undefined

package/src/env/Env.ts

@@ -5,6 +5,7 @@ import {
   removeIdentifier,
 } from './interpolate.js'
 import { loadEnvFiles } from './loadEnvFiles.js'
+import { normalizeNodeEnv } from './nodeEnv.js'
 import { type SchemaNode, schema } from './schema.js'
 
 /**
@@ -87,7 +88,7 @@ export class Env<Values extends Record<string, unknown>> {
     appRoot: URL,
     schema: S,
   ): Promise<Env<EnvRecord<S>>> {
-    loadEnvFiles(appRoot, { skipEnvLocal: process.env.NODE_ENV === 'test' })
+    loadEnvFiles(appRoot, { skipEnvLocal: normalizeNodeEnv(process.env.NODE_ENV) === 'test' })
 
     return new Env(Env.rules(schema).validate(process.env))
   }

package/src/env/loadEnvFiles.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { parseEnv } from 'node:util'
 import { interpolate } from './interpolate.js'
+import { normalizeNodeEnv } from './nodeEnv.js'
 
 /**
  * Load `.env` files into `process.env` — the shared primitive behind both the
@@ -17,7 +18,10 @@ import { interpolate } from './interpolate.js'
  *   developer's local overrides don't leak into tests).
  */
 export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
-  const nodeEnv = process.env.NODE_ENV
+  // Normalised, so `NODE_ENV=prod` loads `.env.production` — the file the
+  // deployment actually wrote — instead of looking for `.env.prod`.
+  const raw = normalizeNodeEnv(process.env.NODE_ENV)
+  const nodeEnv = raw === 'unknown' ? undefined : raw
   const files = [
     nodeEnv ? `.env.${nodeEnv}.local` : null,
     options.skipEnvLocal ? null : '.env.local',

package/src/env/nodeEnv.ts

@@ -0,0 +1,38 @@
+/**
+ * Reading `NODE_ENV`, with the aliases people actually set.
+ *
+ * `NODE_ENV=prod` is a normal thing to find in a Dockerfile or a platform's
+ * dashboard, and a bare `=== 'production'` reads it as "not production": the
+ * app then serves without Secure cookies, with development error pages, and
+ * loads the wrong `.env` file. Normalising once, here, is what stops that
+ * spelling from deciding how an application behaves.
+ *
+ * The tables mirror upstream exactly. Anything outside them is handed back
+ * lowercased rather than forced into a bucket — `staging` stays `staging`, so
+ * `.env.staging` still resolves.
+ */
+
+const DEV_ENVS = ['dev', 'develop', 'development']
+const PROD_ENVS = ['prod', 'production']
+const TEST_ENVS = ['test', 'testing']
+
+/**
+ * The canonical name for whatever `NODE_ENV` holds.
+ *
+ * Returns `'unknown'` when it is unset — an absent environment is not the
+ * development one, and pretending otherwise turns a misconfigured deploy into
+ * a silently permissive one.
+ */
+export function normalizeNodeEnv(value: string | undefined): string {
+  if (!value || typeof value !== 'string') return 'unknown'
+  const env = value.toLowerCase()
+  if (DEV_ENVS.includes(env)) return 'development'
+  if (PROD_ENVS.includes(env)) return 'production'
+  if (TEST_ENVS.includes(env)) return 'test'
+  return env
+}
+
+/** The current environment, normalised. */
+export function currentNodeEnv(): string {
+  return normalizeNodeEnv(process.env.NODE_ENV)
+}

package/src/errors/ReamError.ts

@@ -7,6 +7,8 @@
  * @implements FR71, FR72, FR73, FR77
  */
 
+import { currentNodeEnv } from '../env/nodeEnv.js'
+
 /**
  * Is this a Ream error, and one of these codes?
  *
@@ -39,7 +41,12 @@ export function isReamError(error: unknown, ...codes: string[]): boolean {
 }
 
 export class ReamError extends Error {
-  /** Error code (e.g., "ATLAS_QUERY_ERROR", "CONTAINER_NOT_FOUND") */
+  /**
+   * Error code, `E_`-prefixed as every framework code is — an application
+   * matching on one should never have to remember which convention a
+   * particular package followed (e.g. "E_ATLAS_QUERY_ERROR",
+   * "E_CONTAINER_NOT_FOUND").
+   */
   readonly code: string
 
   /** Additional context key-value pairs */
@@ -164,6 +171,6 @@ export class ReamError extends Error {
    * Auto-format based on NODE_ENV.
    */
   toFormattedString(): string {
-    return process.env.NODE_ENV === 'production' ? this.toProdString() : this.toDevString()
+    return currentNodeEnv() === 'production' ? this.toProdString() : this.toDevString()
   }
 }

package/src/graphql/GraphQLEngine.ts

@@ -22,6 +22,7 @@
  */
 
 import * as fs from 'node:fs'
+import { currentNodeEnv } from '../env/nodeEnv.js'
 import { loadNapi } from '../helpers/napi-loader.js'
 import type { HttpContext } from '../http/HttpContext.js'
 
@@ -231,7 +232,7 @@ export class GraphQLEngine {
     }
     this.#schemaSource = fs.readFileSync(config.schemaPath, 'utf8')
     this.path = config.path ?? '/graphql'
-    this.#playground = config.playground ?? process.env.NODE_ENV !== 'production'
+    this.#playground = config.playground ?? currentNodeEnv() !== 'production'
     this.#maxQueryBytes = config.maxQueryBytes ?? 100_000
     this.#maxDepth = config.maxDepth ?? 12
     this.#maxComplexity = config.maxComplexity ?? 1000
@@ -288,7 +289,7 @@ export class GraphQLEngine {
       ctx.response.status(200).json(result)
     } catch (err) {
       const message =
-        process.env.NODE_ENV !== 'production' && err instanceof Error
+        currentNodeEnv() !== 'production' && err instanceof Error
           ? err.message
           : 'Internal server error'
       ctx.response.status(500).json({ errors: [{ message }] })

package/src/http/Exception.ts

@@ -7,6 +7,7 @@
  */
 
 import { format } from 'node:util'
+import { currentNodeEnv } from '../env/nodeEnv.js'
 import { Macroable } from '../utils/Macroable.js'
 import type { HttpContext } from './HttpContext.js'
 
@@ -272,7 +273,7 @@ type LogLevel = 'error' | 'warn' | 'info'
 export class ExceptionHandler extends Macroable {
   protected debug: boolean
   /** Render `statusPages` (browser HTML). Defaults to production only (AdonisJS). */
-  protected renderStatusPages: boolean = process.env.NODE_ENV === 'production'
+  protected renderStatusPages: boolean = currentNodeEnv() === 'production'
   /** Status → HTML renderer, keys may be single codes or `'500..599'` ranges. */
   protected statusPages: Record<string, StatusPageRenderer> = {}
   /** Master reporting switch (AdonisJS `reportErrors`). */

package/src/http/Request.ts

@@ -383,7 +383,14 @@ export class Request extends Macroable {
   cookie(name: string, defaultValue?: string): string | null
   cookie(name: string, defaultValue?: string): string | null {
     const raw = this.plainCookie<string>(name, undefined, { encoded: false })
-    const value = raw === null ? null : this.#cookieSigner ? this.#cookieSigner.unsign(raw) : raw
+    // No signer means nothing here was ever signed. Handing the raw value back
+    // would present whatever the client wrote as a verified one — the reader
+    // cannot tell the difference, which is exactly the confusion signing
+    // exists to remove. `plainCookie()` is the way to read an unsigned value.
+    if (!this.#cookieSigner) return defaultValue ?? null
+    // The name is part of the signature, so a value moved to another cookie
+    // fails here rather than being honoured under its new name.
+    const value = raw === null ? null : this.#cookieSigner.unsign<string>(raw, name)
     return value ?? defaultValue ?? null
   }
 
@@ -675,20 +682,29 @@ export class Request extends Macroable {
   }
 
   /**
-   * A JSON-safe view of the request (AdonisJS `serialize`), for logs and error
-   * reports. Carries no body: it may hold credentials, and a log line is the
-   * last place they should land.
+   * A JSON view of the request (AdonisJS `serialize`).
+   *
+   * The whole request, as upstream reports it: body, cookies and every header
+   * verbatim. It is a debugging dump, and it carries credentials — an
+   * `authorization` header, a session cookie, a password field in the body.
+   *
+   * Do not put it in a log line. {@link serializeSafe} is the one built for
+   * that.
    */
   serialize(): Record<string, unknown> {
     return {
       id: this.id(),
       url: this.url(true),
+      query: this.parsedUrl().search?.slice(1) ?? '',
+      body: this.body(),
+      params: this.params(),
+      headers: this.headers(),
       method: this.method(),
       protocol: this.protocol(),
-      host: this.host(),
-      headers: this.headers(),
-      qs: this.qs(),
-      params: this.params(),
+      cookies: this.cookies(),
+      hostname: this.hostname(),
+      ip: this.ip(),
+      subdomains: this.subdomains(),
     }
   }
 
@@ -697,6 +713,28 @@ export class Request extends Macroable {
     return this.serialize()
   }
 
+  /**
+   * A view fit for a log line or an error report.
+   *
+   * Not upstream's — it has no such method, and its `serialize()` is a full
+   * dump. This one carries no body and no cookies, and the headers that hold a
+   * credential come back as `[redacted]` rather than as their value: the header
+   * is still LISTED, because knowing a request arrived with an `authorization`
+   * header is most of what a reader wants, and its contents are none of it.
+   */
+  serializeSafe(): Record<string, unknown> {
+    return {
+      id: this.id(),
+      url: this.url(true),
+      method: this.method(),
+      protocol: this.protocol(),
+      host: this.host(),
+      headers: redactSensitiveHeaders(this.headers()),
+      qs: this.qs(),
+      params: this.params(),
+    }
+  }
+
   // ─── Query string ─────────────────────────────────────────
 
   /** Get parsed query string as an object. */
@@ -999,6 +1037,33 @@ function isPlainObject(value: unknown): value is Dict<unknown> {
 }
 
 /** True for an IPv4 dotted-quad or a (bracketed) IPv6 literal — hosts with no subdomains. */
+/**
+ * Headers whose VALUE is a credential. Listing them is useful; printing them
+ * hands whoever reads the log a working key.
+ */
+const SENSITIVE_HEADERS = new Set([
+  'authorization',
+  'proxy-authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'x-auth-token',
+  'x-access-token',
+  'x-csrf-token',
+  'x-xsrf-token',
+  'x-session-token',
+  'x-amz-security-token',
+])
+
+/** Replace each credential-bearing header's value with a marker, keeping the name. */
+function redactSensitiveHeaders(headers: Dict): Dict {
+  const out: Dict = {}
+  for (const [name, value] of Object.entries(headers)) {
+    out[name] = SENSITIVE_HEADERS.has(name.toLowerCase()) ? '[redacted]' : value
+  }
+  return out
+}
+
 function isIpLiteral(host: string): boolean {
   if (host.startsWith('[') || host.includes('::')) return true
   return /^(\d{1,3}\.){3}\d{1,3}$/.test(host)

package/src/http/Response.ts

@@ -13,6 +13,7 @@ import { readFile, stat } from 'node:fs/promises'
 import { basename } from 'node:path'
 import etag from 'etag'
 import { contentType } from 'mime-types'
+import { ReamError } from '../errors/ReamError.js'
 import { durationToSeconds } from '../helpers/duration.js'
 
 /**
@@ -60,8 +61,6 @@ function assertNoCRLF(name: string, value: string): void {
  */
 function contentDisposition(disposition: string, filename: string): string {
   const quoted = filename.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
-  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching control
-  // characters is the point — they cannot travel in a header field.
   const ascii = quoted.replace(/[^\x20-\x7e]/g, '_')
   const base = `${disposition}; filename="${ascii}"`
   if (ascii === quoted) return base
@@ -285,7 +284,7 @@ export class Response extends Macroable {
   /** Send a JSON response. Sets content-type and stringifies. */
   json(data: unknown): void {
     this.#headers['content-type'] = 'application/json'
-    this.#body = safeStringify(data)
+    this.#setBody(safeStringify(data))
     this.#finished = true
   }
 
@@ -315,7 +314,7 @@ export class Response extends Macroable {
       c === '\u2028' ? '\\u2028' : '\\u2029',
     )
     this.#headers['content-type'] = 'text/javascript; charset=utf-8'
-    this.#body = `/**/ typeof ${safeCallback} === 'function' && ${safeCallback}(${json});`
+    this.#setBody(`/**/ typeof ${safeCallback} === 'function' && ${safeCallback}(${json});`)
     this.#finished = true
   }
 
@@ -330,7 +329,7 @@ export class Response extends Macroable {
           ? 'text/html; charset=utf-8'
           : 'text/plain; charset=utf-8'
       }
-      this.#body = data
+      this.#setBody(data)
     } else if (Buffer.isBuffer(data)) {
       // Without this branch a Buffer would hit the `typeof === 'object'`
       // path and be JSON-stringified into `{"type":"Buffer","data":[...]}`
@@ -339,12 +338,12 @@ export class Response extends Macroable {
       return
     } else if (typeof data === 'object' && data !== null) {
       this.#headers['content-type'] = 'application/json'
-      this.#body = safeStringify(data)
+      this.#setBody(safeStringify(data))
     } else if (data !== undefined && data !== null) {
       if (!this.#headers['content-type']) {
         this.#headers['content-type'] = 'text/plain'
       }
-      this.#body = String(data)
+      this.#setBody(String(data))
     }
     this.#finished = true
   }
@@ -383,12 +382,37 @@ export class Response extends Macroable {
    * `@c9up/archive` instead and let the client fetch it from storage — the
    * bytes then never pass through the server at all.
    */
+  /**
+   * Assign the body, refusing one too large to hold.
+   *
+   * Every textual path goes through here — `json()`, `send()`, `jsonp()`, a
+   * middleware rewriting the body. The ceiling used to live only in
+   * `sendBuffer()`, so `json(hugeObject)` and `send(hugeString)` walked past
+   * it and the process grew until it died, which is the failure the ceiling
+   * exists to name.
+   *
+   * Measured in UTF-8 BYTES, not characters: a string of accented or CJK text
+   * is one and a half to three times its length on the wire.
+   */
+  #setBody(body: string): void {
+    this.#assertBodyFits(Buffer.byteLength(body, 'utf8'))
+    this.#body = body
+  }
+
   #assertBodyFits(bytes: number): void {
     if (bytes <= this.#maxBodyBytes) return
-    throw new Error(
-      `[E_RESPONSE_TOO_LARGE] Response body is ${Math.round(bytes / 1_048_576)}MB, over the ${Math.round(this.#maxBodyBytes / 1_048_576)}MB ceiling. ` +
-        'The body is held whole in memory (and base64-encoded, ~2.3x) because responses are not streamed yet. ' +
-        'Raise `maxResponseBytes` in the kernel config, or serve large files with a signed URL from @c9up/archive.',
+    throw new ReamError(
+      'E_RESPONSE_TOO_LARGE',
+      `Response body is ${Math.round(bytes / 1_048_576)}MB, over the ${Math.round(this.#maxBodyBytes / 1_048_576)}MB ceiling.`,
+      {
+        context: {
+          bytes: String(bytes),
+          ceiling: String(this.#maxBodyBytes),
+        },
+        hint:
+          'The body is held whole in memory (and base64-encoded, ~2.3x) because responses are not streamed yet. ' +
+          'Raise `maxResponseBytes` in the kernel config, or serve large files with a signed URL from @c9up/archive.',
+      },
     )
   }
 
@@ -665,7 +689,11 @@ export class Response extends Macroable {
    */
   redirect(): RedirectBuilder
   redirect(path: string, forwardQueryString?: boolean, statusCode?: number): void
-  redirect(path?: string, forwardQueryString = false, statusCode = 302): RedirectBuilder | void {
+  redirect(
+    path?: string,
+    forwardQueryString = false,
+    statusCode = 302,
+  ): RedirectBuilder | undefined {
     if (!this.#redirectBuilderFactory) {
       throw new Error(
         'redirect() requires an HttpContext. Response was created outside a request handler.',
@@ -1063,14 +1091,25 @@ export class Response extends Macroable {
   // ─── Cookies ──────────────────────────────────────────────
 
   /**
-   * Set a SIGNED response cookie (AdonisJS default). The value is HMAC-signed
-   * with the app's `APP_KEY` (via the injected signer) so tampering is detected
-   * on read; `request.cookie()` verifies + unwraps it. Falls back to a plain
-   * cookie when no APP_KEY / encryption service is configured.
+   * Set a SIGNED response cookie (the default). The value is HMAC-signed with
+   * the app's `APP_KEY`, so tampering is detected on read; `request.cookie()`
+   * verifies and unwraps it.
+   *
+   * Requires APP_KEY, and REFUSES rather than falling back to a plain cookie.
+   * A silent fallback is the worst of both: the caller asked for integrity,
+   * the value ships without it, and `request.cookie()` on the far side hands
+   * back whatever the client wrote as though it had been verified.
+   *
+   * The cookie's NAME is signed along with its value, so a signed cookie
+   * cannot be lifted onto another name and still verify.
    */
   cookie(name: string, value: string, options?: CookieOptions): this {
-    const signed = this.#cookieSigner ? this.#cookieSigner.sign(value) : value
-    return this.#writeCookie(name, signed, options)
+    if (!this.#cookieSigner) {
+      throw new Error(
+        'cookie() signs the value and needs APP_KEY — set it so the encryption service is registered, or use plainCookie() when the value does not need signing.',
+      )
+    }
+    return this.#writeCookie(name, this.#cookieSigner.sign(value, undefined, name), options)
   }
 
   /**
@@ -1262,7 +1301,7 @@ export class Response extends Macroable {
 
   /** @internal Set body directly (used by redirect, exception handler). */
   setBody(body: string): void {
-    this.#body = body
+    this.#setBody(body)
     this.#finished = true
   }
 

package/src/index.ts

@@ -347,12 +347,16 @@ export {
 export type {
   ErrorReporter,
   LockBackend,
+  LockBackendFactory,
+  LockRedisClient,
+  LockRedisResolver,
   RunTaskOutcome,
   ScheduleEvent,
   ScheduleEventSink,
   ScheduleInvocation,
   ScheduleMetadata,
   ScheduleProviderOptions,
+  SchedulerConfig,
   SchedulerOptions,
   ScheduleTaskCompletedEvent,
   ScheduleTaskFailedEvent,
@@ -362,8 +366,11 @@ export type {
   TaskStats,
 } from './scheduler/index.js'
 export {
+  defineSchedulerConfig,
   getScheduleMetadata,
+  locks,
   MemoryLockBackend,
+  RedisLockBackend,
   SCHEDULE_METADATA_KEY,
   Schedule,
   ScheduleProvider,
@@ -371,4 +378,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.9'
+export const VERSION = '0.2.11'

package/src/router/Router.ts

@@ -1602,12 +1602,21 @@ function matchPath(pattern: string, actual: string): MatchedParams | null {
   return params
 }
 
-/** Match domain pattern against actual host. Supports wildcards like *.example.com */
+/**
+ * Match a domain pattern against the request's host. Supports wildcards like
+ * `*.example.com`.
+ *
+ * Both sides are lowercased: a hostname is case-insensitive (RFC 4343), so a
+ * client that sends `API.Example.COM` — which is legal, and what some proxies
+ * and older clients do — must reach the same route as `api.example.com`.
+ * Comparing them verbatim sends that request to a fallback, or to a 404.
+ */
 function matchDomain(pattern: string, host: string): boolean {
-  const actualHost = host.split(':')[0] // strip port
-  if (pattern === actualHost) return true
-  if (pattern.startsWith('*.')) {
-    const suffix = pattern.slice(1) // ".example.com"
+  const actualHost = host.split(':')[0].toLowerCase() // strip port
+  const wanted = pattern.toLowerCase()
+  if (wanted === actualHost) return true
+  if (wanted.startsWith('*.')) {
+    const suffix = wanted.slice(1) // ".example.com"
     return actualHost.endsWith(suffix) && actualHost.length > suffix.length
   }
   return false

package/src/rpc/RpcRouter.ts

@@ -18,6 +18,7 @@ import {
   parseRequest as parseRpcRequest,
   buildError as rpcError,
 } from '@c9up/comet'
+import { currentNodeEnv } from '../env/nodeEnv.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import type { MiddlewareRegistry, RuntimeValidator } from '../middleware/Pipeline.js'
 import { composeMiddleware, runValidator } from '../middleware/Pipeline.js'
@@ -316,7 +317,7 @@ export class RpcRouter {
         return rpcError(err.code, message, id, err.data)
       }
       // Otherwise don't leak internal error details to the caller.
-      const isDev = process.env.NODE_ENV !== 'production'
+      const isDev = currentNodeEnv() !== 'production'
       const message = isDev && err instanceof Error ? err.message : 'Internal error'
       return rpcError(-32603, message, id)
     }