@c9up/ream 0.1.32 → 0.1.34

package/src/http/RedirectBuilder.ts

@@ -28,14 +28,23 @@ function isSameOriginOrRelative(referer: string, requestUrl?: string): boolean {
   }
 }
 
+/** The slice of the session the intended-URL methods use. */
+export interface IntendedUrlStore {
+  setIntendedUrl(url: string): void
+  pullIntendedUrl(): string | null
+}
+
 export class RedirectBuilder {
   #response: Response
   #status = 302
-  #qs: Record<string, string> | null = null
+  #qs: Record<string, unknown> = {}
   #forwardQs = false
   #requestUrl?: string
   #requestReferer?: string
   #routeUrlResolver?: RouteUrlResolver
+  #session?: IntendedUrlStore
+  #isAjax = false
+  #hasRoute = true
 
   constructor(
     response: Response,
@@ -43,12 +52,77 @@ export class RedirectBuilder {
       requestUrl?: string
       requestReferer?: string
       routeUrlResolver?: RouteUrlResolver
+      /** The request session, for the intended-URL methods. */
+      session?: IntendedUrlStore
+      /** Whether this is an XHR — `withIntendedUrl` skips those. */
+      isAjax?: boolean
+      /** Whether a route matched — `withIntendedUrl` skips 404s. */
+      hasRoute?: boolean
     },
   ) {
     this.#response = response
     this.#requestUrl = options?.requestUrl
     this.#requestReferer = options?.requestReferer
     this.#routeUrlResolver = options?.routeUrlResolver
+    this.#session = options?.session
+    this.#isAjax = options?.isAjax ?? false
+    this.#hasRoute = options?.hasRoute ?? true
+  }
+
+  /**
+   * Remember where the user was heading, then carry on redirecting — AdonisJS'
+   * `withIntendedUrl` (a macro `@adonisjs/session` adds to Redirect).
+   *
+   * Only a GET, non-XHR, route-matched request is stored, exactly as upstream:
+   * remembering a POST would replay it as a GET after login, and remembering a
+   * 404 would send the user back to a dead end.
+   */
+  withIntendedUrl(method = 'GET'): this {
+    if (
+      this.#session &&
+      method.toUpperCase() === 'GET' &&
+      !this.#isAjax &&
+      this.#hasRoute &&
+      this.#requestUrl
+    ) {
+      this.#session.setIntendedUrl(this.#requestUrl)
+    }
+    return this
+  }
+
+  /**
+   * Redirect to the remembered URL, consuming it — AdonisJS' `toIntended`.
+   *
+   * The stored value is validated before use: it is written from a request URL,
+   * but a session store is not a trust boundary, and a redirect to an absolute
+   * off-site URL is an open redirect. Anything not same-origin or relative
+   * falls back, which is what `back()` already does with the Referer.
+   */
+  toIntended(fallback = '/'): void {
+    const intended = this.#session?.pullIntendedUrl() ?? null
+    this.toPath(this.#safeIntended(intended, fallback))
+  }
+
+  /** `toIntended`, falling back to a named route — AdonisJS' `toIntendedRoute`. */
+  toIntendedRoute(name: string, params?: Record<string, string>): void {
+    const intended = this.#session?.pullIntendedUrl() ?? null
+    const safe = intended === null ? null : this.#safeIntended(intended, null)
+    if (safe !== null) {
+      this.toPath(safe)
+      return
+    }
+    this.toRoute(name, params)
+  }
+
+  #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
   }
 
   /** Set redirect status code. */
@@ -57,13 +131,42 @@ export class RedirectBuilder {
     return this
   }
 
-  /** Forward current query string to the redirect target. */
-  withQs(qs?: Record<string, string>): this {
-    if (qs) {
-      this.#qs = qs
-    } else {
+  /**
+   * Query string for the redirect target, in the four shapes AdonisJS accepts:
+   *
+   *   withQs()                 forward the request's own query string
+   *   withQs(false)            stop forwarding it
+   *   withQs({ a: 1, b: 2 })   merge these values in
+   *   withQs('a', 1)           set one value
+   *
+   * The object and name/value forms MERGE, as upstream does — calling it twice
+   * adds to what is there rather than replacing it.
+   */
+  withQs(): this
+  withQs(forward: boolean): this
+  withQs(values: Record<string, unknown>): this
+  withQs(name: string, value: unknown): this
+  withQs(name?: boolean | string | Record<string, unknown>, value?: unknown): this {
+    if (name === undefined) {
       this.#forwardQs = true
+      return this
+    }
+    if (typeof name === 'boolean') {
+      this.#forwardQs = name
+      return this
     }
+    if (typeof name === 'string') {
+      this.#qs[name] = value
+      return this
+    }
+    Object.assign(this.#qs, name)
+    return this
+  }
+
+  /** Drop every value added with {@link withQs}, and stop forwarding. */
+  clearQs(): this {
+    this.#qs = {}
+    this.#forwardQs = false
     return this
   }
 
@@ -98,14 +201,26 @@ export class RedirectBuilder {
     }
   }
 
+  /**
+   * Forwarded query string first, explicit values on top — the order AdonisJS
+   * uses, so `withQs()` plus `withQs('page', 2)` overrides an inbound `page`
+   * rather than being overridden by it.
+   */
   #appendQs(path: string): string {
-    let qs = ''
-    if (this.#qs) {
-      qs = new URLSearchParams(this.#qs).toString()
-    } else if (this.#forwardQs && this.#requestUrl) {
+    const params = new URLSearchParams()
+    if (this.#forwardQs && this.#requestUrl) {
       const qsIdx = this.#requestUrl.indexOf('?')
-      if (qsIdx !== -1) qs = this.#requestUrl.slice(qsIdx + 1)
+      if (qsIdx !== -1) {
+        for (const [key, value] of new URLSearchParams(this.#requestUrl.slice(qsIdx + 1))) {
+          params.append(key, value)
+        }
+      }
+    }
+    for (const [key, value] of Object.entries(this.#qs)) {
+      if (value === undefined || value === null) continue
+      params.set(key, String(value))
     }
+    const qs = params.toString()
     if (!qs) return path
     return path.includes('?') ? `${path}&${qs}` : `${path}?${qs}`
   }

package/src/http/Request.ts

@@ -12,6 +12,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 { unpackCookieValue } from './Response.js'
 
 export interface RawRequest {
   method: string
@@ -60,7 +61,7 @@ export interface RawRequest {
 
 export class Request extends Macroable {
   #raw: RawRequest
-  #params: Dict
+  #params: Dict<string | string[]>
   #cookieSigner?: CookieSigner
   #signedUrl?: SignedUrl
   #allowMethodSpoofing = false
@@ -71,6 +72,8 @@ export class Request extends Macroable {
   #parsedQs: Dict<unknown> | undefined
   #merged: Dict<unknown> | undefined
   #original: Dict<unknown> | undefined
+  /** Set by {@link updateRawBody}; `raw()` reports it instead of the wire body. */
+  #rawBodyOverride: string | undefined
   #files: Map<string, import('../bodyparser/MultipartFile.js').MultipartFile[]> = new Map()
   #validated: unknown
 
@@ -91,7 +94,7 @@ export class Request extends Macroable {
    */
   csrfProtected?: boolean
 
-  constructor(raw: RawRequest, params: Dict = {}) {
+  constructor(raw: RawRequest, params: Dict<string | string[]> = {}) {
     super()
     this.#raw = raw
     this.#params = params
@@ -202,6 +205,22 @@ export class Request extends Macroable {
     this.#trustProxy = enabled
   }
 
+  /**
+   * The HTTP/2 `:authority` pseudo-header, falling back to `Host` (AdonisJS
+   * `authority`).
+   *
+   * Deliberately does NOT consult `X-Forwarded-Host` and ignores trust-proxy,
+   * as Adonis does: no proxy convention forwards the original `:authority`,
+   * so honouring a forwarded header here would let a proxy rewrite the value
+   * you validate a redirect target against. Use {@link host} when you do want
+   * the proxy-aware value.
+   */
+  authority(): string | null {
+    const pseudo = this.#raw.headers[':authority']
+    if (pseudo) return pseudo
+    return this.#raw.headers.host ?? null
+  }
+
   /**
    * The request host including port (AdonisJS `host`). Honours
    * `X-Forwarded-Host` ONLY when trust-proxy is enabled; otherwise the `Host`
@@ -312,16 +331,44 @@ export class Request extends Macroable {
    * `defaultValue` (or null) when absent OR when the signature is invalid
    * (tampered / not signed).
    */
+  cookie(name: string): string | null
+  cookie(name: string, defaultValue: string): string
+  cookie(name: string, defaultValue?: string): string | null
   cookie(name: string, defaultValue?: string): string | null {
-    const raw = this.plainCookie(name)
+    const raw = this.plainCookie<string>(name, undefined, { encoded: false })
     const value = raw === null ? null : this.#cookieSigner ? this.#cookieSigner.unsign(raw) : raw
     return value ?? defaultValue ?? null
   }
 
-  /** Raw (unsigned) cookie value (AdonisJS `plainCookie`), or `defaultValue`/null when absent. */
-  plainCookie(name: string, defaultValue?: string): string | null {
+  /**
+   * An unsigned cookie (AdonisJS `plainCookie`), unpacked.
+   *
+   * `response.plainCookie()` writes a base64url JSON envelope, so this reads
+   * the value BACK WITH ITS TYPE — an object stays an object, a number a
+   * number. A cookie set by something else, or written with `encode: false`,
+   * comes back as the raw string.
+   *
+   * Pass `encoded: false` to skip unpacking entirely.
+   */
+  plainCookie<T = string>(name: string): T | null
+  plainCookie<T = string>(name: string, defaultValue: T, options?: { encoded?: boolean }): T
+  plainCookie<T = string>(
+    name: string,
+    defaultValue: undefined,
+    options?: { encoded?: boolean },
+  ): T | null
+  plainCookie<T = string>(name: string, defaultValue?: T, options?: { encoded?: boolean }): T | null
+  plainCookie<T = string>(
+    name: string,
+    defaultValue?: T,
+    options?: { encoded?: boolean },
+  ): T | null {
     const cookies = this.#raw.cookies ?? this.cookies()
-    return cookies[name] ?? defaultValue ?? null
+    const raw = cookies[name]
+    if (raw === undefined) return defaultValue ?? null
+    // Caller's claim about an untyped store, same contract as `input<T>`.
+    if (options?.encoded === false) return raw as T
+    return unpackCookieValue(raw) as T
   }
 
   /**
@@ -329,8 +376,11 @@ export class Request extends Macroable {
    * Returns `defaultValue` (or null) when absent, undecryptable, or no
    * encryption service.
    */
+  encryptedCookie(name: string): string | null
+  encryptedCookie(name: string, defaultValue: string): string
+  encryptedCookie(name: string, defaultValue?: string): string | null
   encryptedCookie(name: string, defaultValue?: string): string | null {
-    const raw = this.plainCookie(name)
+    const raw = this.plainCookie<string>(name, undefined, { encoded: false })
     const value = raw === null || !this.#cookieSigner ? null : this.#cookieSigner.decrypt(raw)
     return value ?? defaultValue ?? null
   }
@@ -353,6 +403,7 @@ export class Request extends Macroable {
 
   /** Get the raw body as a string (decoded from base64 if binary). */
   raw(): string {
+    if (this.#rawBodyOverride !== undefined) return this.#rawBodyOverride
     if (this.#raw.bodyEncoding === 'base64') {
       return Buffer.from(this.#raw.body, 'base64').toString('utf8')
     }
@@ -370,6 +421,9 @@ export class Request extends Macroable {
   // ─── Headers ──────────────────────────────────────────────
 
   /** Get a single request header (case-insensitive), or `defaultValue` when absent. */
+  header(key: string): string | undefined
+  header(key: string, defaultValue: string): string
+  header(key: string, defaultValue?: string): string | undefined
   header(key: string, defaultValue?: string): string | undefined {
     return this.#raw.headers[key.toLowerCase()] ?? defaultValue
   }
@@ -381,16 +435,219 @@ export class Request extends Macroable {
 
   // ─── Route params ─────────────────────────────────────────
 
-  /** Get a single route parameter. */
+  /**
+   * Get a single route parameter.
+   *
+   * The catch-all `*` is an ARRAY of segments (AdonisJS hands it that way), so
+   * it is returned joined here — `param('*')` reading `undefined` because the
+   * value was not a string would be worse than the path it describes.
+   * Use {@link params} to get the segments themselves.
+   */
+  param(key: string): string | undefined
+  param(key: string, defaultValue: string): string
+  param(key: string, defaultValue?: string): string | undefined
   param(key: string, defaultValue?: string): string | undefined {
-    return this.#params[key] ?? defaultValue
+    const value = this.#params[key]
+    if (value === undefined) return defaultValue
+    return Array.isArray(value) ? value.join('/') : value
   }
 
-  /** Get all route parameters. */
-  params(): Readonly<Dict> {
+  /** Get all route parameters; `*` holds its segments as an array. */
+  params(): Readonly<Dict<string | string[]>> {
     return this.#params
   }
 
+  // ─── Identity and shape ───────────────────────────────────
+
+  /**
+   * The request id from `x-request-id` (AdonisJS `id`).
+   *
+   * Absent when the proxy or client did not set one — it is not invented here,
+   * because a correlation id nobody else knows correlates nothing.
+   */
+  id(): string | undefined {
+    return this.header('x-request-id')
+  }
+
+  /** The URL split into path and raw query string (AdonisJS `parsedUrl`). */
+  parsedUrl(): { pathname: string; search: string; query: string } {
+    const query = this.#raw.query ?? ''
+    return {
+      pathname: this.#raw.path,
+      search: query ? `?${query}` : '',
+      query,
+    }
+  }
+
+  /** `X-Requested-With: xmlhttprequest` (AdonisJS `ajax`). */
+  ajax(): boolean {
+    return (this.header('x-requested-with') ?? '').toLowerCase() === 'xmlhttprequest'
+  }
+
+  /** Whether the client sent `X-Pjax` (AdonisJS `pjax`). */
+  pjax(): boolean {
+    return this.header('x-pjax') !== undefined
+  }
+
+  /**
+   * Whether this is a speculative prefetch or prerender rather than a real
+   * navigation (AdonisJS `prefetch`).
+   *
+   * Worth checking before anything with a side effect: a browser may fetch a
+   * link the user never clicks, and counting that as a visit — or worse, acting
+   * on it — attributes an intention nobody had.
+   */
+  prefetch(): boolean {
+    const purpose = (
+      this.header('sec-purpose') ??
+      this.header('purpose') ??
+      this.header('x-purpose') ??
+      this.header('x-moz') ??
+      ''
+    ).toLowerCase()
+    return purpose.includes('prefetch') || purpose.includes('prerender')
+  }
+
+  /**
+   * The full URL — `protocol://host/path` (AdonisJS `completeUrl`).
+   *
+   * Pass `true` to keep the query string.
+   */
+  completeUrl(includeQueryString = false): string {
+    const path = includeQueryString ? this.url(true) : this.url(false)
+    return `${this.protocol()}://${this.host()}${path}`
+  }
+
+  /**
+   * Where the user came from, per the `Referer` header — but only when it
+   * points somewhere we trust (AdonisJS `getPreviousUrl`).
+   *
+   * A referrer is attacker-controlled, so redirecting back to it unchecked is
+   * an open redirect. The host must be this request's own or one of
+   * `allowedHosts`; anything else falls back.
+   */
+  getPreviousUrl(allowedHosts: string[] = [], fallback = '/'): string {
+    const referer = this.header('referer') ?? this.header('referrer')
+    if (!referer) return fallback
+    let parsed: URL
+    try {
+      parsed = new URL(referer)
+    } catch {
+      return fallback
+    }
+    const trusted = new Set([this.host(), ...allowedHosts])
+    if (!trusted.has(parsed.host)) return fallback
+    return `${parsed.pathname}${parsed.search}`
+  }
+
+  // ─── Content negotiation ──────────────────────────────────
+
+  /** Every media type the client accepts, best first (AdonisJS `types`). */
+  types(): string[] {
+    return this.#negotiated('accept')
+  }
+
+  /** Every language the client accepts, best first (AdonisJS `languages`). */
+  languages(): string[] {
+    return this.#negotiated('accept-language')
+  }
+
+  /** Every charset the client accepts, best first (AdonisJS `charsets`). */
+  charsets(): string[] {
+    return this.#negotiated('accept-charset')
+  }
+
+  /**
+   * The best of the offered charsets per `Accept-Charset` (AdonisJS
+   * `charset`), or null when none matches. The plural {@link charsets} lists
+   * everything the client will take.
+   */
+  charset<T extends string>(charsets: T[]): T | null {
+    return this.#bestOf('accept-charset', charsets)
+  }
+
+  /** Every encoding the client accepts, best first (AdonisJS `encodings`). */
+  encodings(): string[] {
+    return this.#negotiated('accept-encoding')
+  }
+
+  /**
+   * The best of the offered encodings per `Accept-Encoding` (AdonisJS
+   * `encoding`), or null when none matches.
+   */
+  encoding<T extends string>(encodings: T[]): T | null {
+    return this.#bestOf('accept-encoding', encodings)
+  }
+
+  /**
+   * The best of the offered values for one `Accept-*` header (AdonisJS
+   * `charset` / `encoding`).
+   *
+   * Client preference decides: the header's q-order is walked first, and the
+   * order the server offered them only breaks a tie within one q-bucket —
+   * the same rule {@link accepts} follows. An absent header means the client
+   * expressed no preference, so the server's first offer wins.
+   */
+  #bestOf<T extends string>(header: string, offered: T[]): T | null {
+    const raw = this.#raw.headers[header]
+    if (!raw?.trim()) return offered[0] ?? null
+    const entries = parseAcceptHeader(raw)
+    if (entries.length === 0) return null
+    for (const bucket of bucketByQ(entries)) {
+      for (const value of offered) {
+        for (const entry of bucket) {
+          const candidate = entry.value.toLowerCase()
+          if (candidate === '*' || candidate === value.toLowerCase()) return value
+        }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Parse one `Accept-*` header into the client's preference order.
+   *
+   * Sorted by q descending, ties broken by the order the client wrote them —
+   * which is what "preference" means when two entries share a q.
+   */
+  #negotiated(header: string): string[] {
+    const raw = this.#raw.headers[header]
+    if (!raw) return []
+    return parseAcceptHeader(raw)
+      .sort((a, b) => b.q - a.q || a.index - b.index)
+      .map((entry) => entry.value)
+  }
+
+  // ─── Serialization ────────────────────────────────────────
+
+  /** Every cookie, parsed (AdonisJS `cookiesList`). */
+  cookiesList(): Dict {
+    return this.cookies()
+  }
+
+  /**
+   * 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.
+   */
+  serialize(): Record<string, unknown> {
+    return {
+      id: this.id(),
+      url: this.url(true),
+      method: this.method(),
+      protocol: this.protocol(),
+      host: this.host(),
+      headers: this.headers(),
+      qs: this.qs(),
+      params: this.params(),
+    }
+  }
+
+  /** Same as {@link serialize} — what `JSON.stringify(request)` uses. */
+  toJSON(): Record<string, unknown> {
+    return this.serialize()
+  }
+
   // ─── Query string ─────────────────────────────────────────
 
   /** Get parsed query string as an object. */
@@ -500,7 +757,7 @@ export class Request extends Macroable {
    * Aliases (`'json'` ↔ `application/json`, `'html'` ↔ `text/html`,
    * `'xml'` ↔ any subtype containing `xml`) are honoured.
    */
-  accepts(types: string[]): string | null {
+  accepts<T extends string>(types: T[]): T | null {
     const header = this.#raw.headers.accept ?? '*/*'
     const entries = parseAcceptHeader(header)
     if (entries.length === 0) return null
@@ -523,7 +780,7 @@ export class Request extends Macroable {
    * primary subtag) matches the highest-q client entry, falling back to
    * `langs[0]` when nothing matches and the client header is empty/absent.
    */
-  language(langs: string[]): string | null {
+  language<T extends string>(langs: T[]): T | null {
     const header = this.#raw.headers['accept-language'] ?? ''
     if (!header.trim()) return langs[0] ?? null
     const entries = parseAcceptHeader(header)
@@ -601,6 +858,39 @@ export class Request extends Macroable {
     this.#merged = undefined // reset merged cache
   }
 
+  /**
+   * Replace the request body (AdonisJS `updateBody`) — what a middleware that
+   * sanitizes or normalises input calls. {@link all} is recomputed from the
+   * query string and the new body on the next read.
+   *
+   * {@link original} keeps the first-seen input: flash old-input must show
+   * what the user actually sent, not what a middleware rewrote it into.
+   */
+  updateBody(body: Dict<unknown>): void {
+    this.all() // snapshot the original before it is replaced
+    this.setParsedBody(body)
+  }
+
+  /**
+   * Replace the query string data (AdonisJS `updateQs`). {@link all} is
+   * recomputed on the next read; the raw query string is left alone, so
+   * `parsedUrl()` still reports what the client sent.
+   */
+  updateQs(data: Dict<unknown>): void {
+    this.all()
+    this.#parsedQs = { ...data }
+    this.#merged = undefined
+  }
+
+  /**
+   * Replace the raw body (AdonisJS `updateRawBody`) — what the bodyparser
+   * sets when it cannot parse the body, or for multipart. Does NOT reparse:
+   * the parsed body is whatever {@link updateBody} last set.
+   */
+  updateRawBody(rawBody: string): void {
+    this.#rawBodyOverride = rawBody
+  }
+
   /**
    * @internal Store the validated + transformed payload (called by the
    * validation middleware after a route validator passes).