@c9up/ream 0.2.28 → 0.2.29

package/src/server/Server.ts

@@ -37,12 +37,20 @@ export type MiddlewareEntry = LazyImport<MiddlewareClassConstructor> | Middlewar
 export interface GrpcCall {
   /** `/package.Service/Method`, as it arrived. */
   path: string
-  /** Request metadata, header names lowercased. */
-  metadata: Record<string, string>
+  /**
+   * Request metadata: the request headers, every value of a repeated one in
+   * order, names lowercased. Never the client's trailers.
+   */
+  metadata: Record<string, string[]>
   /** The request message, still encoded. */
   message: Uint8Array
   /** Resolved client IP, by the same trusted-proxy rules as `request.ip()`. */
   ip: string
+  /**
+   * Aborted when the client gives up on the call — resets its stream or
+   * closes the connection — before the handler answered.
+   */
+  signal: AbortSignal
 }
 
 /** A reply message, still encoded — or a gRPC status code instead of one. */
@@ -50,6 +58,26 @@ export type GrpcReply = { message: Uint8Array } | { code: number; details: strin
 
 export type GrpcHandler = (call: GrpcCall) => Promise<GrpcReply>
 
+/**
+ * Message size bounds of the gRPC calls, in bytes; `-1` for none. A request
+ * past its bound is refused, `RESOURCE_EXHAUSTED`, before it is read; a reply
+ * past its bound is answered `RESOURCE_EXHAUSTED` instead.
+ */
+export interface GrpcLimits {
+  /** Default 4 MiB. */
+  maxReceiveMessageLength?: number
+  /** Default `-1`: no bound. */
+  maxSendMessageLength?: number
+}
+
+function checkGrpcLimit(name: string, value: number | undefined): void {
+  if (value === undefined || value === -1 || (Number.isSafeInteger(value) && value >= 0)) return
+  throw new ReamError(
+    'E_SERVER_GRPC_INVALID_LIMIT',
+    `${name} must be a whole number of bytes, or -1 for no limit — got ${value}.`,
+  )
+}
+
 export class Server {
   #router: Router
   #serverMiddleware: MiddlewareFunction[] = []
@@ -57,22 +85,31 @@ export class Server {
   #resolvedErrorHandler?: ExceptionHandler
   #trustedProxies: string[] = []
   #grpcHandler?: GrpcHandler
+  #grpcLimits: GrpcLimits = {}
 
   constructor(router: Router) {
     this.#router = router
   }
 
   /**
-   * Configure the trusted-proxy CIDR list. The Rust HyperServer uses it to
-   * pre-resolve `request.ip` once per request — JS reads the field, no CIDR
-   * matching in TS.
+   * Configure the trusted proxies. The Rust HyperServer uses them to
+   * pre-resolve `request.ip()` / `request.ips()` once per request — JS reads
+   * the fields, no CIDR matching in TS.
+   *
+   * The chain is the socket peer, then the `X-Forwarded-For` entries read
+   * right to left; it stops at the first hop that is not a trusted proxy, and
+   * its last entry is the client IP. Proxies append what they saw, so the
+   * left-most entry — the one a client writes itself — is only reached when
+   * every hop after it is trusted. `X-Real-IP` is never read.
    *
-   * Empty list (default, 2026-05+) is **strict fail-closed**: `X-Forwarded-For`
-   * and `X-Real-IP` are ignored entirely; only the socket peer is used.
-   * Apps deployed behind a reverse proxy must list the proxy's CIDR
-   * (`'10.0.0.0/8'`, `'192.0.2.0/24'`, etc.) or pass the `'*'` sentinel
-   * for permissive mode (accepts spoofing as the explicit trade-off when
-   * proxy CIDRs can't be enumerated).
+   * Entries: addresses or CIDR ranges, IPv4 or IPv6 (`'10.0.0.0/8'`,
+   * `'fd00::/8'`), IPv4 netmasks (`'10.0.0.0/255.0.0.0'`), the named ranges
+   * `'loopback'`, `'linklocal'`, `'uniquelocal'`, or `'*'` to trust every hop
+   * (the left-most entry wins — any client can choose its IP). An entry that is
+   * none of these makes the server refuse to start.
+   *
+   * Empty list (default) is **strict fail-closed**: `X-Forwarded-For` is
+   * ignored and only the socket peer is used.
    */
   trustedProxies(cidrs: string[]): this {
     this.#trustedProxies = [...cidrs]
@@ -99,16 +136,24 @@ export class Server {
    * One handler per server: a second one throws. Two packages both serving
    * gRPC is a conflict to resolve, not to settle by load order.
    */
-  grpc(handler: GrpcHandler): this {
+  grpc(handler: GrpcHandler, limits: GrpcLimits = {}): this {
     if (this.#grpcHandler) {
       throw new ReamError('E_SERVER_GRPC_ALREADY_SET', 'A gRPC handler is already registered.', {
         hint: 'Only one package can serve gRPC on the HTTP port.',
       })
     }
+    checkGrpcLimit('maxReceiveMessageLength', limits.maxReceiveMessageLength)
+    checkGrpcLimit('maxSendMessageLength', limits.maxSendMessageLength)
     this.#grpcHandler = handler
+    this.#grpcLimits = { ...limits }
     return this
   }
 
+  /** The message bounds given with the gRPC handler (consumed by Ignitor at boot). */
+  getGrpcLimits(): GrpcLimits {
+    return { ...this.#grpcLimits }
+  }
+
   /** The gRPC handler, if one is set (consumed by Ignitor at boot). */
   getGrpcHandler(): GrpcHandler | undefined {
     return this.#grpcHandler

package/src/server/nativeGrpc.ts

@@ -0,0 +1,59 @@
+/**
+ * The gRPC handler as the native server calls it.
+ *
+ * The native server numbers each call and, separately, reports the numbers
+ * of the calls a client gave up on — a reset stream or a closed connection —
+ * before the handler answered. This turns those reports into the `signal` of
+ * each {@link GrpcCall}, so that a handler can stop the work it started.
+ *
+ * Calls reach JavaScript in increasing id order, but a cancel travels on its
+ * own queue and can arrive before its call: one for an id not seen yet is
+ * kept until that call arrives; one for an id already seen and finished is
+ * dropped.
+ */
+
+import type { GrpcCall, GrpcHandler, GrpcReply } from './Server.js'
+
+/** A call as the native server hands it over: numbered, without a signal. */
+export interface NativeGrpcCall extends Omit<GrpcCall, 'signal'> {
+  id: number
+}
+
+export type NativeGrpcHandler = (call: NativeGrpcCall) => Promise<GrpcReply>
+
+export interface CancellableGrpc {
+  /** Give to the native server's `onGrpc`. */
+  onCall: NativeGrpcHandler
+  /** Give to the native server's `onGrpcCancel`. */
+  onCancel: (id: number) => void
+}
+
+export function cancellableGrpc(handler: GrpcHandler): CancellableGrpc {
+  const running = new Map<number, AbortController>()
+  // Cancels that arrived before their call.
+  const early = new Set<number>()
+  let lastSeen = 0
+
+  return {
+    async onCall({ id, ...call }) {
+      lastSeen = Math.max(lastSeen, id)
+      const controller = new AbortController()
+      for (const cancelled of early) {
+        if (cancelled > id) continue
+        early.delete(cancelled)
+        if (cancelled === id) controller.abort()
+      }
+      running.set(id, controller)
+      try {
+        return await handler({ ...call, signal: controller.signal })
+      } finally {
+        running.delete(id)
+      }
+    },
+    onCancel(id) {
+      const controller = running.get(id)
+      if (controller !== undefined) controller.abort()
+      else if (id > lastSeen) early.add(id)
+    },
+  }
+}

package/src/server/nativeLimits.ts

@@ -0,0 +1,94 @@
+/**
+ * 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[]
+}
+
+/** Body limits per body-parser section; an omitted section keeps its default. */
+export interface NativeBodyLimits {
+  json?: NativeBodyLimit
+  form?: NativeBodyLimit
+  raw?: NativeBodyLimit
+  multipart?: NativeBodyLimit
+}
+
+/** 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
+  }
+  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()`

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

@@ -9,8 +9,9 @@ const SWEEP_THRESHOLD = 1000
  * 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
 
@@ -78,9 +79,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

@@ -150,8 +150,11 @@ export class StaticMiddleware {
     const reqPath = ctx.request.path()
 
     // 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
     }
@@ -335,25 +338,21 @@ export class StaticMiddleware {
       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 +366,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 +427,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.