@c9up/ream 0.1.25 → 0.1.27

package/dist/http/RedirectBuilder.js

@@ -9,7 +9,10 @@
  *   response.redirect().toRoute('posts.show', { id: '42' })
  */
 function isSameOriginOrRelative(referer, requestUrl) {
-    if (referer.startsWith('/') && !referer.startsWith('//'))
+    // 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;
     if (!requestUrl)
         return false;

package/dist/http/RedirectBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"RedirectBuilder.js","sourceRoot":"","sources":["../../src/http/RedirectBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RedirectBuilder.js","sourceRoot":"","sources":["../../src/http/RedirectBuilder.ts"],"names":[],"mappings":"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"}

package/dist/http/Request.d.ts

@@ -6,7 +6,10 @@
  *
  * @implements FR21
  */
+import type { CookieSigner } from '../security/CookieSigner.js';
+import type { SignedUrl } from '../security/SignedUrl.js';
 import type { Dict } from '../types/helpers.js';
+import { Macroable } from '../utils/Macroable.js';
 export interface RawRequest {
     method: string;
     path: string;
@@ -23,6 +26,12 @@ export interface RawRequest {
      * `ip()` accessor falls back to legacy header parsing.
      */
     ip?: string;
+    /**
+     * Connection scheme as seen by the server (`http`/`https`), when the Rust
+     * layer ships it. Defaults to `http` in `protocol()` when absent; the
+     * `X-Forwarded-Proto` header only overrides it when trust-proxy is enabled.
+     */
+    scheme?: 'http' | 'https';
     /**
      * Pre-parsed `multipart/form-data` payload — the HyperServer parses bodies
      * server-side via `multer` and ships fields/files in this typed shape.
@@ -48,7 +57,7 @@ export interface RawRequest {
      */
     cookies?: Dict;
 }
-export declare class Request {
+export declare class Request extends Macroable {
     #private;
     /**
      * CSRF token for this request (AdonisJS idiom: `request.csrfToken`). Seeded
@@ -56,9 +65,51 @@ export declare class Request {
      * otherwise. Also published to `ctx.store` for templating helpers.
      */
     csrfToken?: string;
+    /**
+     * `true` only when CSRF was enabled, the request method guarded, the route not
+     * excepted, AND the token validated for this request — set by the
+     * `@c9up/blackhole` middleware. Unlike {@link csrfToken} (seeded on every
+     * passing request, even when verification was skipped), this is the trustworthy
+     * "the request was CSRF-verified" signal a consumer reads to fail-close on
+     * state-changing routes. `undefined` when the middleware never ran.
+     */
+    csrfProtected?: boolean;
     constructor(raw: RawRequest, params?: Dict);
-    /** HTTP method (GET, POST, etc.). */
+    /**
+     * The HTTP method, honouring `_method` form spoofing when enabled (AdonisJS
+     * `method`). With spoofing enabled and a real POST, the `_method` field
+     * (`PUT`/`PATCH`/`DELETE`) overrides — the classic HTML-form workaround.
+     * Spoofing is OFF by default (opt in via {@link setMethodSpoofing}); routing
+     * always uses {@link intended}.
+     */
     method(): string;
+    /** The real HTTP method, ignoring any `_method` spoofing (AdonisJS `intended`). */
+    intended(): string;
+    /** @internal Give the request access to its response — wired by HttpContext (for `fresh()`). */
+    setResponse(response: {
+        fresh(): boolean;
+    }): void;
+    /** @internal Record the matched route — wired by HttpContext (for `matchesRoute()`). */
+    setRouteInfo(info: {
+        name?: string;
+        pattern: string;
+    }): void;
+    /**
+     * Whether the client's cached copy is still fresh (AdonisJS `fresh`) —
+     * delegates to the response's `ETag`/`If-None-Match` revalidation check, so a
+     * handler can answer `304 Not Modified`. False before the response is wired.
+     */
+    fresh(): boolean;
+    /** The negation of {@link fresh} (AdonisJS `stale`). */
+    stale(): boolean;
+    /** True when the matched route's name or pattern equals `identifier` (AdonisJS `matchesRoute`). */
+    matchesRoute(identifier: string): boolean;
+    /**
+     * Enable/disable `_method` form spoofing (AdonisJS gates this behind the
+     * `allowMethodSpoofing` config; ream exposes it as an explicit opt-in, off by
+     * default, so an attacker can never silently rewrite a POST into a DELETE).
+     */
+    setMethodSpoofing(enabled: boolean): void;
     /** Request URL (path + query string). */
     url(includeQs?: boolean): string;
     /** Request path (without query string). */
@@ -80,6 +131,41 @@ export declare class Request {
      * desired resolved value.
      */
     ip(): string;
+    /**
+     * 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}).
+     */
+    setTrustProxy(enabled: boolean): void;
+    /**
+     * 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.
+     */
+    host(): string | null;
+    /**
+     * 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`).
+     */
+    protocol(): string;
+    /** True when the request protocol is `https` (AdonisJS `secure`). */
+    secure(): boolean;
+    /**
+     * 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}.
+     */
+    ips(): string[];
+    /** The request hostname without port (AdonisJS `hostname`), or null. */
+    hostname(): string | null;
+    /**
+     * Subdomains of the hostname (AdonisJS `subdomains`). `offset` drops the
+     * registrable domain (default 2 → `example.com`); a leading `www` is removed.
+     * Empty for an IP host or a host with no subdomain.
+     */
+    subdomains(offset?: number): string[];
     /**
      * Return all cookies sent on this request as a name → value map. The
      * HyperServer parses the `Cookie:` header once via the `cookie` crate
@@ -88,14 +174,37 @@ export declare class Request {
      * header — same tolerant `;`-split with quoted-value passthrough.
      */
     cookies(): Dict;
-    /** Pre-parsed cookie value by name, or `null` when absent. */
-    cookie(name: string): string | null;
+    /** Inject the APP_KEY-backed cookie signer — wired by HttpContext. */
+    setCookieSigner(signer: CookieSigner): void;
+    /**
+     * Signed cookie value, verified with APP_KEY (AdonisJS default). Returns
+     * `defaultValue` (or null) when absent OR when the signature is invalid
+     * (tampered / not signed).
+     */
+    cookie(name: string, defaultValue?: string): string | null;
+    /** Raw (unsigned) cookie value (AdonisJS `plainCookie`), or `defaultValue`/null when absent. */
+    plainCookie(name: string, defaultValue?: string): string | null;
+    /**
+     * Encrypted cookie value, decrypted with APP_KEY (AdonisJS `encryptedCookie`).
+     * Returns `defaultValue` (or null) when absent, undecryptable, or no
+     * encryption service.
+     */
+    encryptedCookie(name: string, defaultValue?: string): string | null;
+    /** @internal Inject the APP_KEY-backed signed-URL helper — wired by HttpContext. */
+    setSignedUrl(signedUrl: SignedUrl): void;
+    /**
+     * Verify the request's signed-URL `signature` (AdonisJS `hasValidSignature`).
+     * Delegates to the {@link SignedUrl} helper, which recomputes the HMAC over
+     * the current path + query, rejects an expired `expires`, and checks the
+     * `purpose`. Returns false without an APP_KEY-backed signer.
+     */
+    hasValidSignature(purpose?: string): boolean;
     /** Get the raw body as a string (decoded from base64 if binary). */
     raw(): string;
     /** Get the raw body as a Buffer (preserves binary integrity for file uploads). */
     rawBuffer(): Buffer;
-    /** Get a single request header (case-insensitive). */
-    header(key: string): string | undefined;
+    /** Get a single request header (case-insensitive), or `defaultValue` when absent. */
+    header(key: string, defaultValue?: string): string | undefined;
     /** Get all request headers. */
     headers(): Readonly<Dict>;
     /** Get a single route parameter. */
@@ -106,14 +215,36 @@ export declare class Request {
     qs(): Dict<unknown>;
     /** Get the parsed request body. */
     body(): unknown;
-    /** Get a single input value from body or query string. */
+    /**
+     * Get a single input value from body or query string, by AdonisJS
+     * dot-notation (`input('user.address.city')`). Returns `defaultValue` when
+     * the path is absent (parity with `lodash.get`, reimplemented dependency-free).
+     */
     input<T = unknown>(key: string, defaultValue?: T): T;
     /** Get all input (query string merged with body). */
     all(): Dict<unknown>;
-    /** Cherry-pick specific keys from input. */
-    only<K extends string>(keys: K[]): Partial<Record<K, unknown>>;
-    /** Get all input except specific keys. */
+    /**
+     * The original request input, captured once and never mutated (AdonisJS
+     * `request.original`) — the basis for flash "old input" on validation errors.
+     */
+    original(): Dict<unknown>;
+    /**
+     * Cherry-pick specific keys from input, honouring dot-notation for nested
+     * branches (`only(['user.id'])` → `{ user: { id } }`) — AdonisJS `only`
+     * (`lodash.pick`). Absent paths are skipped.
+     */
+    only(keys: string[]): Dict<unknown>;
+    /**
+     * Get all input except specific keys, honouring dot-notation for nested
+     * branches — AdonisJS `except` (`lodash.omit`). Never mutates the input.
+     */
     except(keys: string[]): Dict<unknown>;
+    /**
+     * True when the request carries a body — a `content-length` above zero or a
+     * `transfer-encoding` header (AdonisJS `request.hasBody`). Lets a handler
+     * branch on "was anything sent" without parsing.
+     */
+    hasBody(): boolean;
     /** Check if the request content-type matches any of the given types. */
     is(types: string[]): string | null;
     /**

package/dist/http/Request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Request.d.ts","sourceRoot":"","sources":["../../src/http/Request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Request.d.ts","sourceRoot":"","sources":["../../src/http/Request.ts"],"names":[],"mappings":"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"}

package/dist/http/Request.js

@@ -6,12 +6,21 @@
  *
  * @implements FR21
  */
-export class Request {
+import { Macroable } from '../utils/Macroable.js';
+import { getPath, omitPaths, pickPaths } from '../utils/objectPath.js';
+export class Request extends Macroable {
     #raw;
     #params;
+    #cookieSigner;
+    #signedUrl;
+    #allowMethodSpoofing = false;
+    #trustProxy = false;
+    #routeInfo;
+    #response;
     #parsedBody;
     #parsedQs;
     #merged;
+    #original;
     #files = new Map();
     #validated;
     /**
@@ -20,15 +29,74 @@ export class Request {
      * otherwise. Also published to `ctx.store` for templating helpers.
      */
     csrfToken;
+    /**
+     * `true` only when CSRF was enabled, the request method guarded, the route not
+     * excepted, AND the token validated for this request — set by the
+     * `@c9up/blackhole` middleware. Unlike {@link csrfToken} (seeded on every
+     * passing request, even when verification was skipped), this is the trustworthy
+     * "the request was CSRF-verified" signal a consumer reads to fail-close on
+     * state-changing routes. `undefined` when the middleware never ran.
+     */
+    csrfProtected;
     constructor(raw, params = {}) {
+        super();
         this.#raw = raw;
         this.#params = params;
     }
     // ─── HTTP accessors ───────────────────────────────────────
-    /** HTTP method (GET, POST, etc.). */
+    /**
+     * The HTTP method, honouring `_method` form spoofing when enabled (AdonisJS
+     * `method`). With spoofing enabled and a real POST, the `_method` field
+     * (`PUT`/`PATCH`/`DELETE`) overrides — the classic HTML-form workaround.
+     * Spoofing is OFF by default (opt in via {@link setMethodSpoofing}); routing
+     * always uses {@link intended}.
+     */
     method() {
+        if (this.#allowMethodSpoofing && this.intended().toUpperCase() === 'POST') {
+            const spoofed = this.input('_method', this.intended());
+            if (typeof spoofed === 'string' && spoofed)
+                return spoofed.toUpperCase();
+        }
+        return this.intended();
+    }
+    /** The real HTTP method, ignoring any `_method` spoofing (AdonisJS `intended`). */
+    intended() {
         return this.#raw.method;
     }
+    /** @internal Give the request access to its response — wired by HttpContext (for `fresh()`). */
+    setResponse(response) {
+        this.#response = response;
+    }
+    /** @internal Record the matched route — wired by HttpContext (for `matchesRoute()`). */
+    setRouteInfo(info) {
+        this.#routeInfo = info;
+    }
+    /**
+     * Whether the client's cached copy is still fresh (AdonisJS `fresh`) —
+     * delegates to the response's `ETag`/`If-None-Match` revalidation check, so a
+     * handler can answer `304 Not Modified`. False before the response is wired.
+     */
+    fresh() {
+        return this.#response?.fresh() ?? false;
+    }
+    /** The negation of {@link fresh} (AdonisJS `stale`). */
+    stale() {
+        return !this.fresh();
+    }
+    /** True when the matched route's name or pattern equals `identifier` (AdonisJS `matchesRoute`). */
+    matchesRoute(identifier) {
+        if (!this.#routeInfo)
+            return false;
+        return this.#routeInfo.name === identifier || this.#routeInfo.pattern === identifier;
+    }
+    /**
+     * Enable/disable `_method` form spoofing (AdonisJS gates this behind the
+     * `allowMethodSpoofing` config; ream exposes it as an explicit opt-in, off by
+     * default, so an attacker can never silently rewrite a POST into a DELETE).
+     */
+    setMethodSpoofing(enabled) {
+        this.#allowMethodSpoofing = enabled;
+    }
     /** Request URL (path + query string). */
     url(includeQs = true) {
         if (includeQs && this.#raw.query) {
@@ -61,6 +129,87 @@ export class Request {
             return this.#raw.ip;
         return this.#raw.remoteAddr ?? '127.0.0.1';
     }
+    /**
+     * 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}).
+     */
+    setTrustProxy(enabled) {
+        this.#trustProxy = enabled;
+    }
+    /**
+     * 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.
+     */
+    host() {
+        if (this.#trustProxy) {
+            const forwarded = this.#raw.headers['x-forwarded-host'];
+            if (forwarded)
+                return forwarded.split(',')[0].trim();
+        }
+        return this.#raw.headers.host ?? null;
+    }
+    /**
+     * 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`).
+     */
+    protocol() {
+        if (this.#trustProxy) {
+            const forwarded = this.#raw.headers['x-forwarded-proto'];
+            if (forwarded)
+                return forwarded.split(',')[0].trim().toLowerCase();
+        }
+        return this.#raw.scheme ?? 'http';
+    }
+    /** True when the request protocol is `https` (AdonisJS `secure`). */
+    secure() {
+        return this.protocol() === 'https';
+    }
+    /**
+     * 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}.
+     */
+    ips() {
+        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);
+            }
+        }
+        return [this.ip()];
+    }
+    /** The request hostname without port (AdonisJS `hostname`), or null. */
+    hostname() {
+        const host = this.host();
+        if (host === null)
+            return null;
+        // Strip the port. IPv6 literals are bracketed (`[::1]:3000`) — keep the brackets' contents.
+        if (host.startsWith('['))
+            return host.slice(0, host.indexOf(']') + 1) || host;
+        const colon = host.indexOf(':');
+        return colon === -1 ? host : host.slice(0, colon);
+    }
+    /**
+     * Subdomains of the hostname (AdonisJS `subdomains`). `offset` drops the
+     * registrable domain (default 2 → `example.com`); a leading `www` is removed.
+     * Empty for an IP host or a host with no subdomain.
+     */
+    subdomains(offset = 2) {
+        const hostname = this.hostname();
+        if (hostname === null || isIpLiteral(hostname))
+            return [];
+        const parts = hostname.split('.').reverse().slice(offset);
+        if (parts.length > 0 && parts[parts.length - 1] === 'www')
+            parts.pop();
+        return parts;
+    }
     /**
      * Return all cookies sent on this request as a name → value map. The
      * HyperServer parses the `Cookie:` header once via the `cookie` crate
@@ -93,10 +242,49 @@ export class Request {
         }
         return result;
     }
-    /** Pre-parsed cookie value by name, or `null` when absent. */
-    cookie(name) {
+    /** Inject the APP_KEY-backed cookie signer — wired by HttpContext. */
+    setCookieSigner(signer) {
+        this.#cookieSigner = signer;
+    }
+    /**
+     * Signed cookie value, verified with APP_KEY (AdonisJS default). Returns
+     * `defaultValue` (or null) when absent OR when the signature is invalid
+     * (tampered / not signed).
+     */
+    cookie(name, defaultValue) {
+        const raw = this.plainCookie(name);
+        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, defaultValue) {
         const cookies = this.#raw.cookies ?? this.cookies();
-        return cookies[name] ?? null;
+        return cookies[name] ?? defaultValue ?? null;
+    }
+    /**
+     * Encrypted cookie value, decrypted with APP_KEY (AdonisJS `encryptedCookie`).
+     * Returns `defaultValue` (or null) when absent, undecryptable, or no
+     * encryption service.
+     */
+    encryptedCookie(name, defaultValue) {
+        const raw = this.plainCookie(name);
+        const value = raw === null || !this.#cookieSigner ? null : this.#cookieSigner.decrypt(raw);
+        return value ?? defaultValue ?? null;
+    }
+    /** @internal Inject the APP_KEY-backed signed-URL helper — wired by HttpContext. */
+    setSignedUrl(signedUrl) {
+        this.#signedUrl = signedUrl;
+    }
+    /**
+     * Verify the request's signed-URL `signature` (AdonisJS `hasValidSignature`).
+     * Delegates to the {@link SignedUrl} helper, which recomputes the HMAC over
+     * the current path + query, rejects an expired `expires`, and checks the
+     * `purpose`. Returns false without an APP_KEY-backed signer.
+     */
+    hasValidSignature(purpose) {
+        if (!this.#signedUrl)
+            return false;
+        return this.#signedUrl.verify(this.url(), purpose);
     }
     /** Get the raw body as a string (decoded from base64 if binary). */
     raw() {
@@ -113,9 +301,9 @@ export class Request {
         return Buffer.from(this.#raw.body, 'utf8');
     }
     // ─── Headers ──────────────────────────────────────────────
-    /** Get a single request header (case-insensitive). */
-    header(key) {
-        return this.#raw.headers[key.toLowerCase()];
+    /** Get a single request header (case-insensitive), or `defaultValue` when absent. */
+    header(key, defaultValue) {
+        return this.#raw.headers[key.toLowerCase()] ?? defaultValue;
     }
     /** Get all request headers. */
     headers() {
@@ -145,45 +333,61 @@ export class Request {
         return this.#parsedBody;
     }
     // ─── Merged input (body + qs) ─────────────────────────────
-    /** Get a single input value from body or query string. */
+    /**
+     * Get a single input value from body or query string, by AdonisJS
+     * dot-notation (`input('user.address.city')`). Returns `defaultValue` when
+     * the path is absent (parity with `lodash.get`, reimplemented dependency-free).
+     */
     input(key, defaultValue) {
-        const merged = this.all();
-        if (key in merged) {
-            // biome-ignore lint/suspicious/noExplicitAny: generic accessor — caller brands the value type via T
-            return merged[key];
-        }
-        // biome-ignore lint/suspicious/noExplicitAny: generic default — caller brands the value type via T
-        return defaultValue;
+        // Untyped request data: the caller declares the shape it expects (same
+        // contract as AdonisJS `request.input<T>`, whose return is loose `any`).
+        return getPath(this.all(), key, defaultValue);
     }
     /** Get all input (query string merged with body). */
     all() {
         if (!this.#merged) {
             this.#ensureParsedBody();
             this.#merged = { ...this.qs(), ...this.#parsedBody };
+            // Snapshot the first-seen input as the immutable "original" (flash old-input).
+            if (this.#original === undefined)
+                this.#original = { ...this.#merged };
         }
         return { ...this.#merged };
     }
-    /** Cherry-pick specific keys from input. */
+    /**
+     * The original request input, captured once and never mutated (AdonisJS
+     * `request.original`) — the basis for flash "old input" on validation errors.
+     */
+    original() {
+        this.all(); // ensure the snapshot is captured
+        return { ...(this.#original ?? {}) };
+    }
+    /**
+     * Cherry-pick specific keys from input, honouring dot-notation for nested
+     * branches (`only(['user.id'])` → `{ user: { id } }`) — AdonisJS `only`
+     * (`lodash.pick`). Absent paths are skipped.
+     */
     only(keys) {
-        const merged = this.all();
-        const result = {};
-        for (const key of keys) {
-            if (key in merged) {
-                result[key] = merged[key];
-            }
-        }
-        return result;
+        return pickPaths(this.all(), keys);
     }
-    /** Get all input except specific keys. */
+    /**
+     * Get all input except specific keys, honouring dot-notation for nested
+     * branches — AdonisJS `except` (`lodash.omit`). Never mutates the input.
+     */
     except(keys) {
-        const merged = this.all();
-        const keySet = new Set(keys);
-        const result = {};
-        for (const [k, v] of Object.entries(merged)) {
-            if (!keySet.has(k))
-                result[k] = v;
-        }
-        return result;
+        return omitPaths(this.all(), keys);
+    }
+    /**
+     * True when the request carries a body — a `content-length` above zero or a
+     * `transfer-encoding` header (AdonisJS `request.hasBody`). Lets a handler
+     * branch on "was anything sent" without parsing.
+     */
+    hasBody() {
+        const transferEncoding = this.#raw.headers['transfer-encoding'];
+        if (transferEncoding && transferEncoding.length > 0)
+            return true;
+        const contentLength = Number.parseInt(this.#raw.headers['content-length'] ?? '', 10);
+        return Number.isFinite(contentLength) && contentLength > 0;
     }
     // ─── Content negotiation ──────────────────────────────────
     /** Check if the request content-type matches any of the given types. */
@@ -357,6 +561,12 @@ export class Request {
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/** True for an IPv4 dotted-quad or a (bracketed) IPv6 literal — hosts with no subdomains. */
+function isIpLiteral(host) {
+    if (host.startsWith('[') || host.includes('::'))
+        return true;
+    return /^(\d{1,3}\.){3}\d{1,3}$/.test(host);
+}
 /**
  * Decode a percent-encoded segment without throwing on malformed input.
  * Browsers happily send `q=%E0%A4%A` (truncated UTF-8 sequences) — refusing