@c9up/ream 0.2.28 → 0.2.30

package/src/http/RedirectBuilder.ts

@@ -13,30 +13,39 @@ import type { Response } from './Response.js'
 
 export type RouteUrlResolver = (name: string, params?: Record<string, string>) => string
 
-function isSameOriginOrRelative(
-  referer: string,
-  requestUrl?: string,
-  allowedHosts: readonly string[] = [],
+/**
+ * AdonisJS `isValidRedirectUrl`: a relative path, or an absolute URL whose host
+ * is the request authority or an allowed host.
+ */
+function isTrustedRedirect(
+  url: string,
+  authority: string | undefined,
+  allowedHosts: readonly string[],
 ): boolean {
   // A relative path is trusted only when it starts with a single "/" and has no
   // backslash: browsers normalise "\" to "/", so "/\evil.com" would become the
   // protocol-relative "//evil.com" that a lone `!startsWith("//")` check misses.
-  if (referer.startsWith('/') && !referer.startsWith('//') && !referer.includes('\\')) return true
-  let ref: URL
-  try {
-    ref = new URL(referer)
-  } catch {
-    return false
-  }
-  // An explicitly allowed host is trusted whatever the request's own origin is
-  // — that is what the list is for (AdonisJS `allowedHosts`).
-  if (allowedHosts.includes(ref.host)) return true
-  if (!requestUrl) return false
+  if (url.startsWith('/') && !url.startsWith('//') && !url.includes('\\')) return true
+  let parsed: URL
   try {
-    return ref.origin === new URL(requestUrl).origin
+    parsed = new URL(url)
   } catch {
     return false
   }
+  // Only a web URL is a redirect target: `javascript://app.test/%0aalert(1)`
+  // has the right host and is a script, not a page.
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
+  if (allowedHosts.includes(parsed.host)) return true
+  // Upstream accepts any absolute URL when it knows no host to compare with;
+  // refusing it is the safer reading of an attacker-controlled header.
+  return authority !== undefined && parsed.host === authority
+}
+
+/** The query string of a path or URL, without the "?". */
+function searchOf(url: string | undefined): string {
+  if (url === undefined) return ''
+  const index = url.indexOf('?')
+  return index === -1 ? '' : url.slice(index + 1)
 }
 
 /** The slice of the session the intended-URL methods use. */
@@ -60,6 +69,7 @@ export class RedirectBuilder {
   #forwardQs = false
   #requestUrl?: string
   #requestReferer?: string
+  #requestAuthority?: string
   #routeUrlResolver?: RouteUrlResolver
   #session?: IntendedUrlStore
   #isAjax = false
@@ -68,8 +78,14 @@ export class RedirectBuilder {
   constructor(
     response: Response,
     options?: {
+      /** The request path with its query string. */
       requestUrl?: string
       requestReferer?: string
+      /**
+       * The request authority (`:authority` or `Host`, never X-Forwarded-Host)
+       * an absolute redirect target must match.
+       */
+      requestAuthority?: string
       routeUrlResolver?: RouteUrlResolver
       /** The request session, for the intended-URL methods. */
       session?: IntendedUrlStore
@@ -82,6 +98,7 @@ export class RedirectBuilder {
     this.#response = response
     this.#requestUrl = options?.requestUrl
     this.#requestReferer = options?.requestReferer
+    this.#requestAuthority = options?.requestAuthority
     this.#routeUrlResolver = options?.routeUrlResolver
     this.#session = options?.session
     this.#isAjax = options?.isAjax ?? false
@@ -135,13 +152,9 @@ export class RedirectBuilder {
 
   #safeIntended<T extends string | null>(intended: string | null, fallback: T): string | T {
     if (!intended) return fallback
-    if (this.#requestUrl && !isSameOriginOrRelative(intended, this.#requestUrl)) {
-      return fallback
-    }
-    // A protocol-relative `//evil.com` is absolute to a browser even though it
-    // looks relative — reject it whether or not a request URL is known.
-    if (intended.startsWith('//')) return fallback
-    return intended
+    return isTrustedRedirect(intended, this.#requestAuthority, this.allowedHosts)
+      ? intended
+      : fallback
   }
 
   /** Set redirect status code. */
@@ -191,7 +204,12 @@ export class RedirectBuilder {
 
   /** Redirect to an absolute or relative path. */
   toPath(path: string): void {
-    const url = this.#appendQs(path)
+    this.#send(path, searchOf(this.#requestUrl))
+  }
+
+  /** Redirect with `withQs()` forwarding `forwardedSearch` (a query string without "?"). */
+  #send(path: string, forwardedSearch: string): void {
+    const url = this.#appendQs(path, forwardedSearch)
     this.#response.status(this.#status)
     this.#response.header('location', url)
     this.#response.setBody('')
@@ -207,12 +225,13 @@ export class RedirectBuilder {
   }
 
   /**
-   * Redirect back to the previous page (Referer header).
-   * Only trusts same-origin or relative referers — external URLs fall back
-   * to `fallback` to prevent open redirect attacks.
+   * Redirect back to the previous page (AdonisJS `back`): the path of
+   * {@link getPreviousUrl}, so the redirect never leaves the site; `withQs()`
+   * forwards the previous page's query string, not the current request's.
    */
   back(fallback = '/'): void {
-    this.toPath(this.getPreviousUrl(fallback))
+    const previous = new URL(this.getPreviousUrl(fallback), 'http://localhost')
+    this.#send(previous.pathname, previous.search.slice(1))
   }
 
   /**
@@ -225,7 +244,7 @@ export class RedirectBuilder {
    */
   getPreviousUrl(fallback = '/'): string {
     const referer = this.#requestReferer
-    if (referer && isSameOriginOrRelative(referer, this.#requestUrl, this.allowedHosts)) {
+    if (referer && isTrustedRedirect(referer, this.#requestAuthority, this.allowedHosts)) {
       return referer
     }
     return fallback
@@ -236,15 +255,10 @@ export class RedirectBuilder {
    * uses, so `withQs()` plus `withQs('page', 2)` overrides an inbound `page`
    * rather than being overridden by it.
    */
-  #appendQs(path: string): string {
+  #appendQs(path: string, forwardedSearch: string): string {
     const params = new URLSearchParams()
-    if (this.#forwardQs && this.#requestUrl) {
-      const qsIdx = this.#requestUrl.indexOf('?')
-      if (qsIdx !== -1) {
-        for (const [key, value] of new URLSearchParams(this.#requestUrl.slice(qsIdx + 1))) {
-          params.append(key, value)
-        }
-      }
+    if (this.#forwardQs) {
+      for (const [key, value] of new URLSearchParams(forwardedSearch)) params.append(key, value)
     }
     for (const [key, value] of Object.entries(this.#qs)) {
       if (value === undefined || value === null) continue

package/src/http/Request.ts

@@ -13,6 +13,7 @@ import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Dict } from '../types/helpers.js'
 import { Macroable } from '../utils/Macroable.js'
 import { getPath, omitPaths, pickPaths } from '../utils/objectPath.js'
+import { Exception } from './Exception.js'
 import type {
   RequestAwareValidator,
   RequestValidationOptions,
@@ -37,6 +38,26 @@ export interface RawRequest {
    * `ip()` accessor falls back to legacy header parsing.
    */
   ip?: string
+  /**
+   * The trusted address chain, closest hop first — the socket peer, then each
+   * `X-Forwarded-For` entry the Rust layer walked right to left while the hop
+   * before it was a trusted proxy. Its last entry is {@link ip}. Absent in
+   * hand-built fixtures, where the chain is the peer alone.
+   */
+  ips?: string[]
+  /**
+   * Whether the socket peer is one of the trusted proxies configured with
+   * `server.trustedProxies()`, as the Rust layer decided against the same
+   * list that resolves {@link ip}. Absent in hand-built fixtures: untrusted.
+   */
+  peerTrusted?: boolean
+  /**
+   * The body was over its content type's limit (`config/bodyparser.ts`): the
+   * Rust layer did not keep it, and `body` is empty. Reading the body then
+   * throws `E_REQUEST_ENTITY_TOO_LARGE` instead of handing back nothing as if
+   * nothing had been sent.
+   */
+  bodyTooLarge?: boolean
   /**
    * Connection scheme as seen by the server (`http`/`https`), when the Rust
    * layer ships it. Defaults to `http` in `protocol()` when absent; the
@@ -72,7 +93,6 @@ export class Request extends Macroable {
   #cookieSigner?: CookieSigner
   #signedUrl?: SignedUrl
   #allowMethodSpoofing = false
-  #trustProxy = false
   #routeInfo?: { name?: string; pattern: string; reference?: string }
   #response?: { fresh(): boolean }
   #parsedBody: Dict<unknown> | undefined
@@ -245,13 +265,17 @@ export class Request extends Macroable {
   }
 
   /**
-   * Enable/disable trusting proxy headers (`X-Forwarded-Proto`/`-Host`/`-For`)
-   * for `protocol()`/`host()`/`ips()`. OFF by default — turning it on when the
-   * app is NOT behind a trusted proxy lets clients spoof their scheme/host/IP,
-   * so it's an explicit opt-in (same stance as {@link setMethodSpoofing}).
+   * Whether the socket peer is one of the trusted proxies configured with
+   * `server.trustedProxies()` — the condition under which `X-Forwarded-Proto`
+   * and `X-Forwarded-Host` are believed by {@link protocol} and {@link host}.
+   *
+   * The decision is the Rust layer's (`peerTrusted`), made once per request
+   * against the same list that resolves {@link ip}, so a trusted proxy that
+   * forwards the scheme or host without an `X-Forwarded-For` is believed too.
+   * A request without the flag — a hand-built fixture — is untrusted.
    */
-  setTrustProxy(enabled: boolean): void {
-    this.#trustProxy = enabled
+  #peerIsTrustedProxy(): boolean {
+    return this.#raw.peerTrusted === true
   }
 
   /**
@@ -272,11 +296,12 @@ export class Request extends Macroable {
 
   /**
    * The request host including port (AdonisJS `host`). Honours
-   * `X-Forwarded-Host` ONLY when trust-proxy is enabled; otherwise the `Host`
-   * header. Returns null when neither is present.
+   * `X-Forwarded-Host` ONLY when the request came through a trusted proxy (see
+   * `server.trustedProxies()`); otherwise the `Host` header. Returns null when
+   * neither is present.
    */
   host(): string | null {
-    if (this.#trustProxy) {
+    if (this.#peerIsTrustedProxy()) {
       const forwarded = this.#raw.headers['x-forwarded-host']
       // The first hop in the list, named rather than indexed: `split` always
       // yields one element, and saying so beats being told it might not.
@@ -287,12 +312,15 @@ export class Request extends Macroable {
   }
 
   /**
-   * The request protocol — `http` or `https` (AdonisJS `protocol`). Honours
-   * `X-Forwarded-Proto` only under trust-proxy; otherwise the connection scheme
-   * the Rust layer reported (defaulting to `http`).
+   * The request protocol — `http` or `https` (AdonisJS `protocol`). A TLS
+   * connection is `https` whatever the headers say. Otherwise
+   * `X-Forwarded-Proto` is honoured only when the request came through a
+   * trusted proxy (see `server.trustedProxies()`), and the connection scheme
+   * the Rust layer reported (defaulting to `http`) is used when it is not.
    */
   protocol(): string {
-    if (this.#trustProxy) {
+    if (this.#raw.scheme === 'https') return 'https'
+    if (this.#peerIsTrustedProxy()) {
       const forwarded = this.#raw.headers['x-forwarded-proto']
       const [first] = forwarded?.split(',') ?? []
       if (first !== undefined) return first.trim().toLowerCase()
@@ -306,20 +334,15 @@ export class Request extends Macroable {
   }
 
   /**
-   * The client IP chain (AdonisJS `ips`). Under trust-proxy, the parsed
-   * `X-Forwarded-For` list (left-most = original client); otherwise just the
-   * single resolved {@link ip}.
+   * The trusted address chain, closest hop first (AdonisJS `ips`): the socket
+   * peer, then each `X-Forwarded-For` hop a trusted proxy vouched for. The
+   * last entry is {@link ip}. Hops added by an untrusted peer are not in it —
+   * the Rust layer stops at the first address it does not trust, so the chain
+   * goes past the peer only when {@link peerTrusted} holds.
    */
   ips(): string[] {
-    if (this.#trustProxy) {
-      const forwarded = this.#raw.headers['x-forwarded-for']
-      if (forwarded) {
-        return forwarded
-          .split(',')
-          .map((value) => value.trim())
-          .filter((value) => value.length > 0)
-      }
-    }
+    const chain = this.#raw.ips
+    if (chain && chain.length > 0 && this.#peerIsTrustedProxy()) return [...chain]
     return [this.ip()]
   }
 
@@ -455,7 +478,9 @@ export class Request extends Macroable {
   encryptedCookie(name: string, defaultValue?: string): string | null
   encryptedCookie(name: string, defaultValue?: string): string | null {
     const raw = this.plainCookie<string>(name, undefined, { encoded: false })
-    const value = raw === null || !this.#cookieSigner ? null : this.#cookieSigner.decrypt(raw)
+    // Decrypted for the purpose it was written under — its own name — so a
+    // value issued as another encrypted cookie is refused here.
+    const value = raw === null || !this.#cookieSigner ? null : this.#cookieSigner.decrypt(raw, name)
     return value ?? defaultValue ?? null
   }
 
@@ -477,17 +502,26 @@ export class Request extends Macroable {
     return this.#signedUrl.verify(this.url(true), purpose)
   }
 
-  /** Get the raw body as a string (decoded from base64 if binary). */
+  /**
+   * Get the raw body as a string (decoded from base64 if binary). Throws
+   * `E_REQUEST_ENTITY_TOO_LARGE` (413) when the body was over its limit: what
+   * the server kept of it is nothing, and nothing is not the body.
+   */
   raw(): string {
     if (this.#rawBodyOverride !== undefined) return this.#rawBodyOverride
+    this.#assertBodyKept()
     if (this.#raw.bodyEncoding === 'base64') {
       return Buffer.from(this.#raw.body, 'base64').toString('utf8')
     }
     return this.#raw.body
   }
 
-  /** Get the raw body as a Buffer (preserves binary integrity for file uploads). */
+  /**
+   * Get the raw body as a Buffer (preserves binary integrity for file uploads).
+   * Throws `E_REQUEST_ENTITY_TOO_LARGE` (413) when the body was over its limit.
+   */
   rawBuffer(): Buffer {
+    this.#assertBodyKept()
     if (this.#raw.bodyEncoding === 'base64') {
       return Buffer.from(this.#raw.body, 'base64')
     }
@@ -716,7 +750,8 @@ export class Request extends Macroable {
       id: this.id(),
       url: this.url(true),
       query: this.parsedUrl().search?.slice(1) ?? '',
-      body: this.body(),
+      // A dump must not throw: an over-limit body is reported as absent.
+      body: this.#bodyWasDropped() ? undefined : this.body(),
       params: this.params(),
       headers: this.headers(),
       method: this.method(),
@@ -724,7 +759,9 @@ export class Request extends Macroable {
       cookies: this.cookies(),
       hostname: this.hostname(),
       ip: this.ip(),
-      subdomains: this.subdomains(),
+      // What the route's domain captured (`ctx.subdomains`), as upstream
+      // serialises it — not the host's labels, which `subdomains()` returns.
+      subdomains: (this.ctx === undefined ? undefined : Reflect.get(this.ctx, 'subdomains')) ?? {},
     }
   }
 
@@ -1062,38 +1099,45 @@ export class Request extends Macroable {
     return this.#validated
   }
 
-  #ensureParsedBody(): void {
-    if (this.#parsedBody !== undefined) return
-    const raw = this.#raw.body
-    if (!raw || raw.length === 0) {
-      this.#parsedBody = {}
-      return
-    }
-    try {
-      const parsed: unknown = JSON.parse(raw)
-      this.#parsedBody = isPlainObject(parsed) ? parsed : { _body: parsed }
-    } catch {
-      this.#parsedBody = {}
+  /** The body was over its limit and nothing has replaced it since. */
+  #bodyWasDropped(): boolean {
+    return (
+      this.#raw.bodyTooLarge === true &&
+      this.#parsedBody === undefined &&
+      this.#rawBodyOverride === undefined
+    )
+  }
+
+  /**
+   * Refuse to read a body the server did not keep. The same 413 the body
+   * parser raises, so a route without it still answers the client properly
+   * the moment it reaches for the body — and a route that never does is not
+   * charged for it.
+   */
+  #assertBodyKept(): void {
+    if (this.#raw.bodyTooLarge === true) {
+      throw new Exception('request entity too large', {
+        status: 413,
+        code: 'E_REQUEST_ENTITY_TOO_LARGE',
+      })
     }
   }
-}
 
-/** Parse a query string (key=value&key2=value2) into an object. */
-/**
- * Test whether an IPv4 address is within a CIDR range. Bare IP entries
- * (`10.0.0.42`) are accepted as `/32`. IPv6 falls back to string equality
- * — a full v6 implementation isn't required by the current security tests.
- */
-/**
- * Type guard for plain JSON-decoded objects. Excludes `null` (which is
- * `typeof === 'object'`) and arrays so consumers can index by string key
- * without a separate runtime check.
- */
-function isPlainObject(value: unknown): value is Dict<unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
+  /**
+   * The body is whatever the body parser decided it is, and `{}` when no
+   * parser claimed it. Nothing is parsed here: a JSON body is only JSON when
+   * its Content-Type says so. Reading any body as JSON let a foreign page
+   * drive a JSON route with a CORS simple request (no Content-Type, or
+   * `text/plain`), which a browser sends cross-site with the user's cookies
+   * and without a preflight.
+   */
+  #ensureParsedBody(): void {
+    if (this.#parsedBody !== undefined) return
+    this.#assertBodyKept()
+    this.#parsedBody = {}
+  }
 }
 
-/** 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.

package/src/http/Response.ts

@@ -13,6 +13,7 @@ import { readFile, stat } from 'node:fs/promises'
 import { basename } from 'node:path'
 import { ReamError } from '../errors/ReamError.js'
 import { durationToSeconds } from '../helpers/duration.js'
+import { toErrnoException } from '../helpers/errors.js'
 import { etag, matchesIfNoneMatch } from './etag.js'
 import { contentType } from './mime.js'
 
@@ -848,7 +849,7 @@ export class Response extends Macroable {
       size = (await stat(filePath)).size
     } catch (error) {
       if (errorCallback) {
-        const [message, status] = errorCallback(error as NodeJS.ErrnoException)
+        const [message, status] = errorCallback(toErrnoException(error))
         this.status(status ?? 404).send(message)
         return
       }
@@ -1002,7 +1003,7 @@ export class Response extends Macroable {
       // The headers are already out, so there is no status left to change: end
       // the body and let the client see a short read. `errorCallback` is still
       // consulted for whatever logging it does.
-      errorCallback?.(err as NodeJS.ErrnoException)
+      errorCallback?.(toErrnoException(err))
     } finally {
       // Never rethrows: this runs detached, and an unhandled rejection here
       // would take the process down over one client's download.
@@ -1022,7 +1023,7 @@ export class Response extends Macroable {
       }
     } catch (err) {
       const [message, status] = errorCallback
-        ? errorCallback(err as NodeJS.ErrnoException)
+        ? errorCallback(toErrnoException(err))
         : ['Cannot process the request', 500]
       this.status(status ?? 500)
       this.send(message)
@@ -1133,7 +1134,9 @@ export class Response extends Macroable {
         'encryptedCookie() requires APP_KEY — set it so the encryption service is registered.',
       )
     }
-    return this.#writeCookie(name, this.#cookieSigner.encrypt(value), options)
+    // The cookie name is the purpose, as for a signed cookie: a value issued
+    // as one encrypted cookie cannot be replayed under another one's name.
+    return this.#writeCookie(name, this.#cookieSigner.encrypt(value, undefined, name), options)
   }
 
   #writeCookie(name: string, value: string, options?: CookieOptions): this {
@@ -1195,10 +1198,15 @@ export class Response extends Macroable {
 
   /**
    * Expire a cookie immediately (AdonisJS `clearCookie`) — re-sends it with
-   * `Max-Age=0`, the RFC 6265 delete-now signal that `cookie()` honours.
+   * `Max-Age=0` and an `Expires` in 1970, the RFC 6265 delete-now signals.
+   *
+   * A browser matches the cookie to replace on its name, domain and path, so
+   * a cookie written with a `domain` (or a `path`) is only cleared when the
+   * same ones are passed here; `secure` and `sameSite` are accepted so a
+   * `SameSite=None` cookie can be cleared at all.
    */
-  clearCookie(name: string, options?: { path?: string }): this {
-    return this.plainCookie(name, '', { ...options, maxAge: 0 })
+  clearCookie(name: string, options?: Omit<CookieOptions, 'maxAge' | 'expires'>): this {
+    return this.plainCookie(name, '', { ...options, maxAge: 0, expires: new Date(0) })
   }
 
   // ─── Internals (used by HttpKernel for NAPI serialization) ─

package/src/http/SseStream.ts

@@ -253,14 +253,13 @@ function encodeFrame(event: string, data: string, eventId?: string): string {
   const lines: string[] = []
   // `event:` and `id:` are single-line tokens — strip CR/LF so a
   // caller-supplied event name or id can't splice extra SSE frames
-  // (the same injection `comment()` guards against). `data` is safe:
-  // it's split on `\n` and each line re-prefixed, so newlines there
-  // stay inside one logical event.
+  // (the same injection `comment()` guards against).
   if (event) lines.push(`event: ${event.replace(/[\r\n]+/g, ' ')}`)
-  // Multi-line data is allowed by SSE but each line must repeat the
-  // `data: ` prefix. Splitting on `\n` keeps the browser's
-  // reassembly intact (it joins back with `\n`).
-  for (const line of data.split('\n')) {
+  // Multi-line data is allowed but each line must repeat the `data: `
+  // prefix. The event-stream parser ends a line on CRLF, LF AND a lone
+  // CR, so split on all three: a payload CR left in place would end the
+  // line and let the rest of the payload forge its own fields.
+  for (const line of data.split(/\r\n|\r|\n/)) {
     lines.push(`data: ${line}`)
   }
   if (eventId) lines.push(`id: ${eventId.replace(/[\r\n]+/g, ' ')}`)

package/src/http/permissions.ts

@@ -0,0 +1,47 @@
+/**
+ * The permission check shared by the route, RPC and GraphQL gates, so the
+ * three cannot drift apart.
+ */
+
+import type { AuthState } from './HttpContext.js'
+
+/**
+ * Whether the request's identity holds every permission in `required` — what
+ * the route, RPC and GraphQL `.permission()` gates ask.
+ *
+ * When the auth state exposes `hasAllPermissions` (the auth layer resolves
+ * permissions itself, as warden does through its rights resolver), its
+ * answer decides: a permission granted only by the resolver passes, one left
+ * only in the payload does not. Anything but `true` denies, and an error from
+ * the resolver propagates rather than grants. Only an auth state without that
+ * method falls back to the payload: top-level `auth.permissions`, or
+ * `auth.user.permissions`.
+ *
+ * When the request was authenticated with a token, each permission must ALSO
+ * be allowed by `auth.user.currentAccessToken`: an intersection, never a
+ * union. A token scope named like a permission grants nothing the user
+ * lacks, and a token limited to `profile` does not carry every permission of
+ * its user. A token whose `allows` cannot be called denies.
+ */
+export async function holdsPermissions(
+  auth: AuthState | undefined,
+  required: readonly string[],
+): Promise<boolean> {
+  if (!(await userHolds(auth, required))) return false
+  const token = auth?.user?.currentAccessToken
+  if (token === undefined || token === null) return true
+  return required.every(
+    (permission) => typeof token.allows === 'function' && token.allows(permission) === true,
+  )
+}
+
+async function userHolds(
+  auth: AuthState | undefined,
+  required: readonly string[],
+): Promise<boolean> {
+  if (typeof auth?.hasAllPermissions === 'function') {
+    return (await auth.hasAllPermissions(required)) === true
+  }
+  const granted = auth?.permissions ?? auth?.user?.permissions ?? []
+  return required.every((permission) => granted.includes(permission))
+}