@zudojs/http 0.0.6 → 1.0.0

package/dist/httpRange/http.range.js

@@ -0,0 +1,341 @@
+/**
+ * HTTP byte-range utilities.
+ *
+ * Implements parsing and resolution of HTTP Range headers, primarily for
+ * byte-range responses such as files and static assets.
+ */
+/* -------------------------------------------------------------------------- */
+/* Constants                                                                  */
+/* -------------------------------------------------------------------------- */
+export const DEFAULT_RANGE_UNIT = "bytes";
+export const MAX_RANGE_COUNT = 128;
+/* -------------------------------------------------------------------------- */
+/* Range Header Parsing                                                       */
+/* -------------------------------------------------------------------------- */
+export function parseRangeHeader(value) {
+    if (!value || value.trim().length === 0) {
+        return undefined;
+    }
+    const separator = value.indexOf("=");
+    if (separator === -1) {
+        return undefined;
+    }
+    const unit = value.slice(0, separator).trim();
+    if (unit.length === 0) {
+        return undefined;
+    }
+    const rangeValue = value.slice(separator + 1).trim();
+    if (rangeValue.length === 0) {
+        return undefined;
+    }
+    const parts = rangeValue.split(",");
+    /*
+     * The count is checked before anything is parsed: a header with 100 000
+     * comma-separated ranges must not be fully parsed and allocated only to be
+     * rejected afterwards.
+     */
+    if (parts.length > MAX_RANGE_COUNT) {
+        return undefined;
+    }
+    const ranges = [];
+    for (const part of parts) {
+        const range = parseByteRange(part);
+        if (range === undefined) {
+            return undefined;
+        }
+        ranges.push(range);
+    }
+    return {
+        unit,
+        ranges,
+    };
+}
+export function parseByteRange(value) {
+    const trimmed = value.trim();
+    const separator = trimmed.indexOf("-");
+    if (separator === -1) {
+        return undefined;
+    }
+    const startValue = trimmed.slice(0, separator).trim();
+    const endValue = trimmed.slice(separator + 1).trim();
+    if (startValue.length === 0 && endValue.length === 0) {
+        return undefined;
+    }
+    const start = startValue.length > 0 ? parseNonNegativeInteger(startValue) : undefined;
+    const end = endValue.length > 0 ? parseNonNegativeInteger(endValue) : undefined;
+    if (startValue.length > 0 && start === undefined) {
+        return undefined;
+    }
+    if (endValue.length > 0 && end === undefined) {
+        return undefined;
+    }
+    if (start === undefined && end === undefined) {
+        return undefined;
+    }
+    if (start !== undefined && end !== undefined && start > end) {
+        return undefined;
+    }
+    return {
+        start,
+        end,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Range Resolution                                                           */
+/* -------------------------------------------------------------------------- */
+export function resolveByteRange(range, size) {
+    validateSize(size);
+    if (size === 0) {
+        return undefined;
+    }
+    /*
+     * "-N" means the final N bytes.
+     */
+    if (range.start === undefined) {
+        const suffixLength = range.end;
+        if (suffixLength === undefined || suffixLength <= 0) {
+            return undefined;
+        }
+        const length = Math.min(suffixLength, size);
+        const start = size - length;
+        const end = size - 1;
+        return {
+            start,
+            end,
+            length,
+        };
+    }
+    const start = range.start;
+    if (start >= size) {
+        return undefined;
+    }
+    /*
+     * An omitted end means through the final byte.
+     */
+    const end = range.end === undefined ? size - 1 : Math.min(range.end, size - 1);
+    if (end < start) {
+        return undefined;
+    }
+    return {
+        start,
+        end,
+        length: end - start + 1,
+    };
+}
+export function resolveRanges(ranges, size) {
+    validateSize(size);
+    return ranges
+        .map((range) => resolveByteRange(range, size))
+        .filter((range) => range !== undefined);
+}
+export function resolveRangeHeader(header, size) {
+    const parsed = parseRangeHeader(header);
+    if (!parsed) {
+        return undefined;
+    }
+    /*
+     * Overlapping and duplicate ranges are coalesced here as well as in
+     * `createRangeResponse`. Without it `bytes=0-0,0-0,...` yields one
+     * multipart part per repetition — roughly 80 bytes of boundary and headers
+     * for each byte of payload.
+     */
+    const ranges = normalizeRanges(resolveRanges(parsed.ranges, size));
+    return {
+        unit: parsed.unit,
+        ranges,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Range Classification                                                       */
+/* -------------------------------------------------------------------------- */
+export function isByteRangeUnit(unit) {
+    return unit.trim().toLowerCase() === DEFAULT_RANGE_UNIT;
+}
+export function isRangeSatisfiable(range, size) {
+    return resolveByteRange(range, size) !== undefined;
+}
+export function hasSatisfiableRanges(ranges, size) {
+    return resolveRanges(ranges, size).length > 0;
+}
+export function isUnsatisfiableRangeHeader(header, size) {
+    const parsed = parseRangeHeader(header);
+    if (!parsed) {
+        return false;
+    }
+    return resolveRanges(parsed.ranges, size).length === 0;
+}
+/* -------------------------------------------------------------------------- */
+/* Range Normalization                                                        */
+/* -------------------------------------------------------------------------- */
+export function normalizeRanges(ranges) {
+    if (ranges.length <= 1) {
+        return [...ranges];
+    }
+    const sorted = [...ranges].sort((a, b) => a.start - b.start);
+    const result = [];
+    for (const range of sorted) {
+        const previous = result[result.length - 1];
+        if (!previous) {
+            result.push(range);
+            continue;
+        }
+        if (range.start <= previous.end + 1) {
+            const end = Math.max(previous.end, range.end);
+            result[result.length - 1] = {
+                start: previous.start,
+                end,
+                length: end - previous.start + 1,
+            };
+            continue;
+        }
+        result.push(range);
+    }
+    return result;
+}
+export function mergeRanges(ranges) {
+    return normalizeRanges(ranges);
+}
+/* -------------------------------------------------------------------------- */
+/* Range Header Formatting                                                    */
+/* -------------------------------------------------------------------------- */
+export function formatRangeHeader(ranges, unit = DEFAULT_RANGE_UNIT) {
+    if (ranges.length === 0) {
+        throw new RangeError("At least one range is required.");
+    }
+    const formatted = ranges.map((range) => formatByteRange(range));
+    return `${unit}=${formatted.join(", ")}`;
+}
+export function formatByteRange(range) {
+    const start = range.start !== undefined ? String(range.start) : "";
+    const end = range.end !== undefined ? String(range.end) : "";
+    if (start.length === 0 && end.length === 0) {
+        throw new RangeError("A byte range must contain a start or end value.");
+    }
+    return `${start}-${end}`;
+}
+/* -------------------------------------------------------------------------- */
+/* Content-Range                                                              */
+/* -------------------------------------------------------------------------- */
+export function formatContentRange(range, size, unit = DEFAULT_RANGE_UNIT) {
+    validateSize(size);
+    if (range.start < 0 || range.end < range.start || range.end >= size) {
+        throw new RangeError("Resolved range is outside the resource bounds.");
+    }
+    return `${unit} ${range.start}-${range.end}/${size}`;
+}
+export function formatUnsatisfiedContentRange(size, unit = DEFAULT_RANGE_UNIT) {
+    validateSize(size);
+    return `${unit} */${size}`;
+}
+/* -------------------------------------------------------------------------- */
+/* Range Response                                                             */
+/* -------------------------------------------------------------------------- */
+export function createRangeResponse(header, size) {
+    validateSize(size);
+    const parsed = parseRangeHeader(header);
+    if (!parsed || !isByteRangeUnit(parsed.unit)) {
+        return {
+            status: 200,
+            ranges: [],
+        };
+    }
+    const ranges = resolveRanges(parsed.ranges, size);
+    if (ranges.length === 0) {
+        return {
+            status: 416,
+            ranges: [],
+            contentRange: formatUnsatisfiedContentRange(size),
+        };
+    }
+    /*
+     * A single satisfiable range is represented by a normal 206 response with
+     * a Content-Range header. Multipart range formatting belongs elsewhere.
+     */
+    const merged = normalizeRanges(ranges);
+    const single = merged.length === 1 ? merged[0] : undefined;
+    if (single !== undefined) {
+        return {
+            status: 206,
+            ranges: merged,
+            contentRange: formatContentRange(single, size),
+        };
+    }
+    return {
+        status: 206,
+        ranges: merged,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Range Request Helpers                                                      */
+/* -------------------------------------------------------------------------- */
+export function isFullResourceRange(range, size) {
+    validateSize(size);
+    return range.start === 0 && range.end === size - 1;
+}
+export function getRangeLength(range) {
+    return range.end - range.start + 1;
+}
+export function sliceRange(value, range) {
+    const result = [];
+    const end = Math.min(range.end, value.length - 1);
+    const start = Math.max(0, range.start);
+    for (let index = start; index <= end; index += 1) {
+        /* `index` is clamped to `[0, value.length - 1]` above, so this read is
+         * in bounds. The cast only restores what `ArrayLike<T>` promises: a
+         * runtime `undefined` here would be a hole in a sparse input, and
+         * skipping it would silently shift every later element. */
+        result.push(value[index]);
+    }
+    return result;
+}
+/* -------------------------------------------------------------------------- */
+/* Range Coalescing                                                           */
+/* -------------------------------------------------------------------------- */
+export function coalesceRanges(ranges, maxRanges = 16) {
+    if (maxRanges <= 0) {
+        throw new RangeError("maxRanges must be greater than zero.");
+    }
+    const merged = normalizeRanges(ranges);
+    if (merged.length <= maxRanges) {
+        return merged;
+    }
+    /*
+     * If a client asks for an excessive number of ranges, combine the ranges
+     * into a bounded number of larger ranges. This prevents unbounded multipart
+     * response overhead.
+     */
+    const result = [];
+    const groupSize = Math.ceil(merged.length / maxRanges);
+    for (let index = 0; index < merged.length; index += groupSize) {
+        const group = merged.slice(index, index + groupSize);
+        const first = group[0];
+        const last = group[group.length - 1];
+        if (first && last) {
+            result.push({
+                start: first.start,
+                end: last.end,
+                length: last.end - first.start + 1,
+            });
+        }
+    }
+    return result;
+}
+/* -------------------------------------------------------------------------- */
+/* Internal Validation                                                        */
+/* -------------------------------------------------------------------------- */
+function parseNonNegativeInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        return undefined;
+    }
+    const number = Number(value);
+    if (!Number.isSafeInteger(number) || number < 0) {
+        return undefined;
+    }
+    return number;
+}
+function validateSize(size) {
+    if (!Number.isSafeInteger(size) || size < 0) {
+        throw new RangeError("Resource size must be a non-negative safe integer.");
+    }
+}
+//# sourceMappingURL=http.range.js.map

package/dist/httpRedirect/http.redirect.d.ts

@@ -0,0 +1,140 @@
+/**
+ * HTTP redirect utilities.
+ *
+ * Provides redirect status classification, Location header handling,
+ * URL resolution, and redirect policy helpers for the HTTP package.
+ */
+export interface RedirectOptions {
+    readonly statusCode?: number;
+    readonly preserveMethod?: boolean;
+    readonly absolute?: boolean;
+    readonly baseURL?: string | URL;
+    /**
+     * Origins an **absolute** destination is permitted to point at. Supply this
+     * whenever the destination derives from user input (`?next=`, a form field,
+     * a cookie): rejecting `javascript:` and `//evil.com` does not stop
+     * `https://evil.com`, and only an allowlist can.
+     */
+    readonly allowedOrigins?: readonly (string | URL)[];
+}
+export interface RedirectResult {
+    readonly statusCode: number;
+    readonly location: string;
+    readonly preserveMethod: boolean;
+}
+export interface RedirectPolicy {
+    readonly maxRedirects: number;
+    readonly preserveMethod: boolean;
+    readonly allowCrossOrigin: boolean;
+    readonly allowDowngrade: boolean;
+}
+export declare const DEFAULT_REDIRECT_STATUS = 302;
+export declare const DEFAULT_MAX_REDIRECTS = 20;
+export declare const REDIRECT_STATUS_CODES: readonly [301, 302, 303, 307, 308];
+export declare function isRedirectStatus(statusCode: number): boolean;
+export declare function isPermanentRedirect(statusCode: number): boolean;
+export declare function isTemporaryRedirect(statusCode: number): boolean;
+export declare function isMethodPreservingRedirect(statusCode: number): boolean;
+export declare function isMethodChangingRedirect(statusCode: number): boolean;
+export declare function getRedirectStatus(statusCode: number | undefined): number;
+export declare function isValidLocation(location: string | URL | undefined | null): boolean;
+export declare function validateLocation(location: string | URL): string;
+export declare function resolveRedirectURL(location: string | URL, currentURL: string | URL): URL;
+export declare function resolveRedirectLocation(location: string | URL, currentURL: string | URL): string;
+export declare function formatLocation(location: string | URL, options?: {
+    readonly absolute?: boolean;
+    readonly baseURL?: string | URL;
+}): string;
+/**
+ * Creates a redirect result.
+ *
+ * The destination is checked against {@link isSafeRedirectProtocol} — this is
+ * the boundary the safety helper was written for and previously never applied
+ * to. When the destination is user-controlled, pass `allowedOrigins` so an
+ * absolute off-site URL is rejected too; scheme filtering alone still permits
+ * `https://evil.com`.
+ */
+export declare function createRedirect(location: string | URL, options?: RedirectOptions): RedirectResult;
+export declare function shouldPreserveRedirectMethod(statusCode: number, method: string): boolean;
+export declare function getRedirectMethod(statusCode: number, method: string): string;
+export declare function createRedirectPolicy(options?: Partial<RedirectPolicy> | undefined): RedirectPolicy;
+export declare function canFollowRedirect(fromURL: string | URL, toURL: string | URL, policy: RedirectPolicy): boolean;
+export declare function resolveRedirectChain(initialURL: string | URL, locations: readonly (string | URL)[], policy?: Partial<RedirectPolicy> | undefined): URL[];
+export declare function hasRedirectLoop(locations: readonly (string | URL)[]): boolean;
+export declare function assertNoRedirectLoop(locations: readonly (string | URL)[]): void;
+export declare function isSameOrigin(left: string | URL, right: string | URL): boolean;
+export declare function isCrossOrigin(left: string | URL, right: string | URL): boolean;
+export declare function isHTTPS(value: string | URL): boolean;
+/**
+ * True when the value carries its own scheme.
+ *
+ * This deliberately does **not** require a hostname. `new URL("javascript:x")`
+ * parses with `protocol === "javascript:"` and `hostname === ""`, so the old
+ * `hostname.length > 0` requirement classified every opaque scheme as
+ * "relative", which is what made `isSafeRedirectProtocol("javascript:…")`
+ * return true.
+ */
+export declare function isAbsoluteURL(value: string): boolean;
+/**
+ * True for a scheme-relative reference such as `//evil.com` or its backslash
+ * and mixed variants (`\\evil.com`, `/\evil.com`, `\/evil.com`).
+ *
+ * `new URL("//evil.com")` throws, so these look "relative" to a naive check —
+ * but a browser resolves `Location: //evil.com` against the current scheme and
+ * navigates off-site. Browsers also normalise `\` to `/` in this position.
+ */
+export declare function isProtocolRelativeURL(value: string): boolean;
+export declare function isRelativeURL(value: string): boolean;
+export declare function toRelativeLocation(target: string | URL, base: string | URL): string;
+/**
+ * True when the destination cannot change the scheme to something dangerous
+ * and cannot silently leave the current origin without an explicit scheme.
+ *
+ * Rejects, in order:
+ * - anything with a scheme that is not `http` or `https` — `javascript:`,
+ *   `data:`, `vbscript:`, `file:`, `blob:`;
+ * - scheme-relative references (`//evil.com`, `\\evil.com`, `/\evil.com`),
+ *   which a browser resolves off-site;
+ * - values containing a control character, a raw newline, or an encoded one.
+ *
+ * A plain path reference (`/account`, `account?x=1`) is safe: the browser
+ * resolves it against the current origin.
+ */
+export declare function isSafeRedirectProtocol(location: string | URL): boolean;
+export declare function isPotentiallyUnsafeRedirect(location: string | URL): boolean;
+/**
+ * Throws unless the destination passes {@link isSafeRedirectProtocol}.
+ */
+export declare function assertSafeRedirect(location: string | URL): string;
+/**
+ * Resolves a caller-supplied (i.e. potentially user-controlled) destination
+ * against an allowlist and returns a safe `Location` value.
+ *
+ * A destination that arrives in a query parameter, a form field or a cookie is
+ * attacker input. Scheme filtering alone is not enough — `https://evil.com` is
+ * a perfectly well-formed https URL — so an absolute destination is accepted
+ * only when its origin is in `allowedOrigins`. Relative path references are
+ * accepted because they cannot leave the current origin, once the
+ * scheme-relative forms above are excluded.
+ *
+ * Returns `fallback` (default `"/"`) when the destination is missing or fails
+ * any check, so a caller can use the result unconditionally.
+ */
+export declare function resolveSafeRedirectTarget(destination: string | URL | undefined | null, options?: {
+    readonly allowedOrigins?: readonly (string | URL)[];
+    readonly fallback?: string;
+}): string;
+/**
+ * Builds the `Location` header for a redirect.
+ *
+ * Enforces {@link isSafeRedirectProtocol} — a `javascript:` or `data:`
+ * destination, or a scheme-relative `//evil.com`, throws rather than being
+ * emitted — and runs the value through the package's single hardened header
+ * validator.
+ */
+export declare function createLocationHeader(location: string | URL): {
+    readonly name: "Location";
+    readonly value: string;
+};
+export declare function getLocationHeader(headers: Headers | Readonly<Record<string, string>>): string | undefined;
+//# sourceMappingURL=http.redirect.d.ts.map